<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Nimble  Reference</title>
    <link rel="stylesheet" type="text/css" href="css/jazzy.css" />
    <link rel="stylesheet" type="text/css" href="css/highlight.css" />
    <meta charset='utf-8'>
    <script src="js/jquery.min.js" defer></script>
    <script src="js/jazzy.js" defer></script>
    
    <script src="js/lunr.min.js" defer></script>
    <script src="js/typeahead.jquery.js" defer></script>
    <script src="js/jazzy.search.js" defer></script>
  </head>
  <body>
    <a title="Nimble  Reference"></a>
    <header>
      <div class="content-wrapper">
        <p><a href="index.html">Nimble 10.0.0 Docs</a> (46% documented)</p>
        <p class="header-right"><a href="https://github.com/Quick/Nimble"><img src="img/gh.png" alt="GitHub"/>View on GitHub</a></p>
        <div class="header-right">
          <form role="search" action="search.json">
            <input type="text" placeholder="Search documentation" data-typeahead>
          </form>
        </div>
      </div>
    </header>
    <div class="content-wrapper">
      <p id="breadcrumbs">
        <a href="index.html">Nimble Reference</a>
        <img id="carat" src="img/carat.png" alt=""/>
        Nimble  Reference
      </p>
    </div>
    <div class="content-wrapper">
      <nav class="sidebar">
        <ul class="nav-groups">
          <li class="nav-group-name">
            <a href="Classes.html">Classes</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Classes/AssertionDispatcher.html">AssertionDispatcher</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/AssertionRecorder.html">AssertionRecorder</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes.html#/BadInstructionException">BadInstructionException</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/BadInstructionException.html">BadInstructionException</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/FailureMessage.html">FailureMessage</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/NMBExpectation.html">NMBExpectation</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/NMBExpectationMessage.html">NMBExpectationMessage</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/NMBObjCBeCloseToPredicate.html">NMBObjCBeCloseToPredicate</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/NMBObjCRaiseExceptionPredicate.html">NMBObjCRaiseExceptionPredicate</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/NMBPredicate.html">NMBPredicate</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/NMBPredicateResult.html">NMBPredicateResult</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/NMBPredicateStatus.html">NMBPredicateStatus</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/NMBStringer.html">NMBStringer</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/NimbleShortXCTestHandler.html">NimbleShortXCTestHandler</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/NimbleXCTestHandler.html">NimbleXCTestHandler</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/SourceLocation.html">SourceLocation</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Global%20Variables.html">Global Variables</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Global%20Variables.html#/s:6Nimble12DefaultDeltaSdvp">DefaultDelta</a>
              </li>
              <li class="nav-group-task">
                <a href="Global%20Variables.html#/s:6Nimble15EXC_TYPES_COUNTSivp">EXC_TYPES_COUNT</a>
              </li>
              <li class="nav-group-task">
                <a href="Global%20Variables.html#/s:6Nimble23MACH_MSG_TYPE_MAKE_SENDs6UInt32Vvp">MACH_MSG_TYPE_MAKE_SEND</a>
              </li>
              <li class="nav-group-task">
                <a href="Global%20Variables.html#/s:6Nimble0A16AssertionHandlerAA0bC0_pvp">NimbleAssertionHandler</a>
              </li>
              <li class="nav-group-task">
                <a href="Global%20Variables.html#/nativeMachExceptionMask">nativeMachExceptionMask</a>
              </li>
              <li class="nav-group-task">
                <a href="Global%20Variables.html#/s:6Nimble23nativeMachExceptionMasks6UInt32Vvp">nativeMachExceptionMask</a>
              </li>
              <li class="nav-group-task">
                <a href="Global%20Variables.html#/nativeThreadState">nativeThreadState</a>
              </li>
              <li class="nav-group-task">
                <a href="Global%20Variables.html#/s:6Nimble17nativeThreadStates5Int32Vvp">nativeThreadState</a>
              </li>
              <li class="nav-group-task">
                <a href="Global%20Variables.html#/nativeThreadStateCount">nativeThreadStateCount</a>
              </li>
              <li class="nav-group-task">
                <a href="Global%20Variables.html#/s:6Nimble22nativeThreadStateCounts6UInt32Vvp">nativeThreadStateCount</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Enums.html">Enumerations</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Enums/ExpectationMessage.html">ExpectationMessage</a>
              </li>
              <li class="nav-group-task">
                <a href="Enums/ExpectationStyle.html">ExpectationStyle</a>
              </li>
              <li class="nav-group-task">
                <a href="Enums/PredicateStatus.html">PredicateStatus</a>
              </li>
              <li class="nav-group-task">
                <a href="Enums/ToSucceedResult.html">ToSucceedResult</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Extensions.html">Extensions</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Extensions/AnySequence.html">AnySequence</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/Array.html">Array</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/Data.html">Data</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/Date.html">Date</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/Double.html">Double</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/Float.html">Float</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/Int.html">Int</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/Int16.html">Int16</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/Int32.html">Int32</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/Int64.html">Int64</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/Int8.html">Int8</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/NSArray.html">NSArray</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/NSDate.html">NSDate</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions.html#/c:objc(cs)NSDictionary">NSDictionary</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/NSException.html">NSException</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions.html#/c:objc(cs)NSHashTable">NSHashTable</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/NSIndexSet.html">NSIndexSet</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions.html#/c:objc(cs)NSMapTable">NSMapTable</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/NSNumber.html">NSNumber</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions.html#/c:objc(cs)NSSet">NSSet</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/NSString.html">NSString</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/String.html">String</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/UInt.html">UInt</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/UInt16.html">UInt16</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/UInt32.html">UInt32</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/UInt64.html">UInt64</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/UInt8.html">UInt8</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Functions.html">Functions</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2neoiyyAA11ExpectationVySDyxq_GG_AESgtSHRzSQR_r0_lF">!=(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2neoiyyAA11ExpectationVySayxGG_AESgtSQRzlF">!=(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2neoiyyAA11ExpectationVyShyxGG_AESgtSHRzlF">!=(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2neoiyyAA11ExpectationVyShyxGG_AESgtSLRzSHRzlF">!=(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2neoiyyAA11ExpectationVyShyxGG_AEtSHRzlF">!=(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2neoiyyAA11ExpectationVyShyxGG_AEtSLRzSHRzlF">!=(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2neoiyyAA11ExpectationVyxG_xSgtSQRzlF">!=(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2neoiyyAA11ExpectationVyxG_xtSQRzlF">!=(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2neoiyyAA11ExpectationVyx_q_q0_q1_q2_q3_tG_x_q_q0_q1_q2_q3_tSgtSQRzSQR_SQR0_SQR1_SQR2_SQR3_r4_lF">!=(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2neoiyyAA11ExpectationVyx_q_q0_q1_q2_tG_x_q_q0_q1_q2_tSgtSQRzSQR_SQR0_SQR1_SQR2_r3_lF">!=(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2neoiyyAA11ExpectationVyx_q_q0_q1_tG_x_q_q0_q1_tSgtSQRzSQR_SQR0_SQR1_r2_lF">!=(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2neoiyyAA11ExpectationVyx_q_q0_tG_x_q_q0_tSgtSQRzSQR_SQR0_r1_lF">!=(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2neoiyyAA11ExpectationVyx_q_tG_x_q_tSgtSQRzSQR_r0_lF">!=(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2aaoiyAA9PredicateVyxGAE_AEtlF">&amp;&amp;(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble1loiyyAA11ExpectationVyAA13NMBComparable_pG_AaE_pSgtF">&lt;(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble1loiyyAA11ExpectationVyxG_xtSLRzlF">&lt;(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2leoiyyAA11ExpectationVyxG_xtAA13NMBComparableRzlF">&lt;=(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2leoiyyAA11ExpectationVyxG_xtSLRzlF">&lt;=(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2eeoiyyAA11ExpectationVySDyxq_GG_AESgtSHRzSQR_r0_lF">==(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2eeoiyyAA11ExpectationVySayxGG_AESgtSQRzlF">==(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2eeoiyyAA11ExpectationVyShyxGG_AESgtSHRzlF">==(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2eeoiyyAA11ExpectationVyShyxGG_AESgtSLRzSHRzlF">==(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2eeoiyyAA11ExpectationVyShyxGG_AEtSHRzlF">==(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2eeoiyyAA11ExpectationVyShyxGG_AEtSLRzSHRzlF">==(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2eeoiyyAA11ExpectationVyxG_xSgtSQRzlF">==(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2eeoiyyAA11ExpectationVyxG_xtSQRzlF">==(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2eeoiyyAA11ExpectationVyx_q_q0_q1_q2_q3_tG_x_q_q0_q1_q2_q3_tSgtSQRzSQR_SQR0_SQR1_SQR2_SQR3_r4_lF">==(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2eeoiyyAA11ExpectationVyx_q_q0_q1_q2_tG_x_q_q0_q1_q2_tSgtSQRzSQR_SQR0_SQR1_SQR2_r3_lF">==(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2eeoiyyAA11ExpectationVyx_q_q0_q1_tG_x_q_q0_q1_tSgtSQRzSQR_SQR0_SQR1_r2_lF">==(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2eeoiyyAA11ExpectationVyx_q_q0_tG_x_q_q0_tSgtSQRzSQR_SQR0_r1_lF">==(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2eeoiyyAA11ExpectationVyx_q_tG_x_q_tSgtSQRzSQR_r0_lF">==(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble1goiyyAA11ExpectationVyAA13NMBComparable_pG_AaE_pSgtF">&gt;(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble1goiyyAA11ExpectationVyxG_xtSLRzlF">&gt;(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2geoiyyAA11ExpectationVyxG_xtAA13NMBComparableRzlF">&gt;=(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2geoiyyAA11ExpectationVyxG_xtSLRzlF">&gt;=(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble14MACH_MSGH_BITSys6UInt32VAD_ADtF">MACH_MSGH_BITS(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble21MACH_MSGH_BITS_REMOTEys6UInt32VADF">MACH_MSGH_BITS_REMOTE(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7allPassyAA9PredicateVyxGADy7ElementQzGSTRzlF">allPass(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7allPassyAA9PredicateVyxGSb7ElementQzKcSTRzlF">allPass(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7allPassyAA9PredicateVyxGSS_Sb7ElementQzKctSTRzlF">allPass(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2beyAA9PredicateVyyXlGyXlSgF">be(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble9beAKindOfyAA9PredicateVySo8NSObjectCGyXlXpF">beAKindOf(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble9beAKindOfyAA9PredicateVyypGxmlF">beAKindOf(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble14beAnInstanceOfyAA9PredicateVySo8NSObjectCGyXlXpF">beAnInstanceOf(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble14beAnInstanceOfyAA9PredicateVyypGxmlF">beAnInstanceOf(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble9beCloseTo_6withinAA9PredicateVyq_Gq__xtSFRz7ElementQy_RszSlR_r0_lF">beCloseTo(_:within:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble9beCloseTo_6withinAA9PredicateVyxGx_SdtAA20NMBDoubleConvertibleRzlF">beCloseTo(_:within:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble9beCloseTo_6withinAA9PredicateVyxGx_xtSFRzlF">beCloseTo(_:within:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7beEmptyAA9PredicateVyAA13NMBCollection_pGyF">beEmpty()</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7beEmptyAA9PredicateVySSGyF">beEmpty()</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7beEmptyAA9PredicateVySo12NSDictionaryCGyF">beEmpty()</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7beEmptyAA9PredicateVySo7NSArrayCGyF">beEmpty()</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7beEmptyAA9PredicateVySo8NSStringCGyF">beEmpty()</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7beEmptyAA9PredicateVyxGySTRzlF">beEmpty()</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7beEmptyAA9PredicateVyxGySTRzs10SetAlgebraRzlF">beEmpty()</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7beEmptyAA9PredicateVyxGys10SetAlgebraRzlF">beEmpty()</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble9beFailure4testAA9PredicateVys6ResultOyxq_GGyq_cSg_ts5ErrorR_r0_lF">beFailure(test:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7beFalseAA9PredicateVySbGyF">beFalse()</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7beFalsyAA9PredicateVyxGySQRzs27ExpressibleByBooleanLiteralRzlF">beFalsy()</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble13beGreaterThanyAA9PredicateVyAA13NMBComparable_pGAaE_pSgF">beGreaterThan(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble13beGreaterThanyAA9PredicateVyxGxSgSLRzlF">beGreaterThan(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble22beGreaterThanOrEqualToyAA9PredicateVyxGxSgAA13NMBComparableRzlF">beGreaterThanOrEqualTo(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble22beGreaterThanOrEqualToyAA9PredicateVyxGxSgSLRzlF">beGreaterThanOrEqualTo(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble13beIdenticalToyAA9PredicateVyyXlGyXlSgF">beIdenticalTo(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble10beLessThanyAA9PredicateVyAA13NMBComparable_pGAaE_pSgF">beLessThan(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble10beLessThanyAA9PredicateVyxGxSgSLRzlF">beLessThan(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble19beLessThanOrEqualToyAA9PredicateVyxGxSgAA13NMBComparableRzlF">beLessThanOrEqualTo(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble19beLessThanOrEqualToyAA9PredicateVyxGxSgSLRzlF">beLessThanOrEqualTo(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble5beNilAA9PredicateVyxGylF">beNil()</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble9beSuccess4testAA9PredicateVys6ResultOyxq_GGyxcSg_ts5ErrorR_r0_lF">beSuccess(test:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble6beTrueAA9PredicateVySbGyF">beTrue()</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble8beTruthyAA9PredicateVyxGySQRzs27ExpressibleByBooleanLiteralRzlF">beTruthy()</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble6beVoidAA9PredicateVyytGyF">beVoid()</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble8beWithinyAA9PredicateVyxGSNyxGSLRzlF">beWithin(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble8beWithinyAA9PredicateVyxGSnyxGSLRzlF">beWithin(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble9beginWithyAA9PredicateVyAA20NMBOrderedCollection_pGypF">beginWith(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble9beginWithyAA9PredicateVySSGSSF">beginWith(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble9beginWithyAA9PredicateVyxG7ElementQzSTRzSQAGRQlF">beginWith(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble9beginWith6prefixAA9PredicateVyxGq_Sg_tSTRzSTR_SQ7ElementRpzAHQy_AIRSr0_lF">beginWith(prefix:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble9beginWith6prefix2byAA9PredicateVyxGq_Sg_Sb7ElementQz_AIQy_tctSTRzSTR_r0_lF">beginWith(prefix:by:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/catchBadInstruction(block:)">catchBadInstruction(block:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble19catchBadInstruction2inAA0cD9ExceptionCSgyyc_tF">catchBadInstruction(in:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7containyAA9PredicateVyAA12NMBContainer_pGSayypSgGF">contain(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7containyAA9PredicateVyAA12NMBContainer_pGypSgd_tF">contain(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7containyAA9PredicateVySSGSSd_tF">contain(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7containyAA9PredicateVySSGSaySSGF">contain(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7containyAA9PredicateVySo8NSStringCGAFd_tF">contain(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7containyAA9PredicateVySo8NSStringCGSayAFGF">contain(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7containyAA9PredicateVyxG7ElementQzd_tSTRzSQAGRQlF">contain(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7containyAA9PredicateVyxG7ElementQzd_ts10SetAlgebraRzSQAGRQlF">contain(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7containyAA9PredicateVyxG7ElementSTQzd_tSTRzs10SetAlgebraRzSQAGRQlF">contain(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7containyAA9PredicateVyxGSay7ElementQzGSTRzSQAGRQlF">contain(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7containyAA9PredicateVyxGSay7ElementQzGs10SetAlgebraRzSQAGRQlF">contain(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7containyAA9PredicateVyxGSay7ElementSTQzGSTRzs10SetAlgebraRzSQAGRQlF">contain(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble24containElementSatisfyingyAA9PredicateVyxGSb0C0Qzc_SStSTRzlF">containElementSatisfying(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble12defaultDeltaxySFRzlF">defaultDelta()</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble13elementsEqualyAA9PredicateVyxGq_SgSTRzSTR_SQ7ElementRpzAGQy_AHRSr0_lF">elementsEqual(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble13elementsEqual_2byAA9PredicateVyxGq_Sg_Sb7ElementQz_AHQy_tctSTRzSTR_r0_lF">elementsEqual(_:by:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7endWithyAA9PredicateVyAA20NMBOrderedCollection_pGypF">endWith(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7endWithyAA9PredicateVySSGSSF">endWith(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7endWithyAA9PredicateVyxG7ElementQzSTRzSQAGRQlF">endWith(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble5equalyAA9PredicateVySDyxq_GGSDyxq_SgGSHRzSQR_r0_lF">equal(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble5equalyAA9PredicateVySayxSgGGAFSQRzlF">equal(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble5equalyAA9PredicateVyShyxGGAESHRzlF">equal(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble5equalyAA9PredicateVyShyxGGAESLRzSHRzlF">equal(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble5equalyAA9PredicateVyShyxGGAESgSHRzlF">equal(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble5equalyAA9PredicateVyShyxGGAESgSLRzSHRzlF">equal(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble5equalyAA9PredicateVyxGxSQRzlF">equal(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble5equalyAA9PredicateVyxGxSgSQRzlF">equal(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble5equalyAA9PredicateVyx_q_q0_q1_q2_q3_tGx_q_q0_q1_q2_q3_tSgSQRzSQR_SQR0_SQR1_SQR2_SQR3_r4_lF">equal(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble5equalyAA9PredicateVyx_q_q0_q1_q2_tGx_q_q0_q1_q2_tSgSQRzSQR_SQR0_SQR1_SQR2_r3_lF">equal(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble5equalyAA9PredicateVyx_q_q0_q1_tGx_q_q0_q1_tSgSQRzSQR_SQR0_SQR1_r2_lF">equal(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble5equalyAA9PredicateVyx_q_q0_tGx_q_q0_tSgSQRzSQR_SQR0_r1_lF">equal(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble5equalyAA9PredicateVyx_q_tGx_q_tSgSQRzSQR_r0_lF">equal(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble6expect4file4line_AA11ExpectationVyxGSS_SuxSgyKXAtlF">expect(file:line:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble6expect4file4line_AA11ExpectationVyxGSS_SuxSgyKcyXKtlF">expect(file:line:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble6expect4file4line_AA11ExpectationVyxGSS_SuxyKcyXKtlF">expect(file:line:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble6expect4file4line_AA11ExpectationVyytGSS_SuyyKcyXKtF">expect(file:line:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble4fail_4file4lineySS_SSSutF">fail(_:file:line:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble4fail_4lineySS_SutF">fail(_:line:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble4fail_8locationySS_AA14SourceLocationCtF">fail(_:location:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble18gatherExpectations8silently7closureSayAA15AssertionRecordVGSb_yyXEtF">gatherExpectations(silently:closure:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble25gatherFailingExpectations8silently7closureSayAA15AssertionRecordVGSb_yyXEtF">gatherFailingExpectations(silently:closure:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble9haveCountyAA9PredicateVyAA13NMBCollection_pGSiF">haveCount(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble9haveCountyAA9PredicateVyxGSiSlRzlF">haveCount(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble5matchyAA9PredicateVySSGSSSgF">match(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble10matchErroryAA9PredicateVys0C0_pGxSQRzsAERzlF">matchError(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble10matchErroryAA9PredicateVys0C0_pGxmsAERzlF">matchError(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble10matchErroryAA9PredicateVys0C0_pGxsAERzlF">matchError(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble28postDistributedNotifications_4from5namesAA9PredicateVyxGAFySay10Foundation12NotificationVGG_So013NSDistributedI6CenterCShySo18NSNotificationNameaGtlF">postDistributedNotifications(_:from:names:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble17postNotifications_4fromAA9PredicateVyxGAEySay10Foundation12NotificationVGG_So20NSNotificationCenterCtlF">postNotifications(_:from:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble20prettyCollectionTypeySSxSlRzlF">prettyCollectionType(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble20prettyCollectionTypeySSxlF">prettyCollectionType(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble14raiseException5named6reason8userInfo7closureAA9PredicateVyxGSSSg_AJSo12NSDictionaryCSgySo11NSExceptionCcSgtlF">raiseException(named:reason:userInfo:closure:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble14raiseException5named6reason8userInfo7closureAA9PredicateVyxGSo15NSExceptionNameaSg_SSSgSo12NSDictionaryCSgySo0J0CcSgtlF">raiseException(named:reason:userInfo:closure:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble13recordFailure_8locationySS_AA14SourceLocationCtF">recordFailure(_:location:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble12satisfyAllOfyAA9PredicateVyxGAEd_tlF">satisfyAllOf(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble12satisfyAllOfyAA9PredicateVyxGSayAEGlF">satisfyAllOf(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble12satisfyAnyOfyAA9PredicateVyxGAEd_tlF">satisfyAnyOf(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble12satisfyAnyOfyAA9PredicateVyxGSayAEGlF">satisfyAnyOf(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble9stringifyySSxSglF">stringify(_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble7succeedAA9PredicateVyAA15ToSucceedResultOGyF">succeed()</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble14throwAssertionAA9PredicateVyxGylF">throwAssertion()</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble10throwErrorAA9PredicateVyxGylF">throwError()</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble10throwError_7closureAA9PredicateVyq_Gx_ys0C0_pcSgtsAGRzr0_lF">throwError(_:closure:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble10throwError_7closureAA9PredicateVyq_Gx_yxcSgtSQRzs0C0Rzr0_lF">throwError(_:closure:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble10throwError7closureAA9PredicateVyq_Gyxc_ts0C0Rzr0_lF">throwError(closure:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble10throwError7closureAA9PredicateVyxGys0C0_pc_tlF">throwError(closure:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble10throwError9errorType7closureAA9PredicateVyq_Gxm_yxcSgts0C0Rzr0_lF">throwError(errorType:closure:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble9waitUntil7timeout4file4line6actiony8Dispatch0H12TimeIntervalO_SSSuyyycctF">waitUntil(timeout:file:line:action:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble20withAssertionHandler_4file4line7closureyAA0cD0_p_SSSuyyKXEtF">withAssertionHandler(_:file:line:closure:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble2oooiyAA9PredicateVyxGAE_AEtlF">||(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble003obaoiyx8expected_Sd5deltatx_SdtAA20NMBDoubleConvertibleRzlF">±(_:_:)</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/s:6Nimble003obaoiyx8expected_x5deltatx_xtSFRzlF">±(_:_:)</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Protocols.html">Protocols</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Protocols/AssertionHandler.html">AssertionHandler</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/NMBCollection.html">NMBCollection</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/NMBComparable.html">NMBComparable</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/NMBContainer.html">NMBContainer</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/NMBDoubleConvertible.html">NMBDoubleConvertible</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/NMBOrderedCollection.html">NMBOrderedCollection</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/TestOutputStringConvertible.html">TestOutputStringConvertible</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Structs.html">Structures</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Structs/AssertionRecord.html">AssertionRecord</a>
              </li>
              <li class="nav-group-task">
                <a href="Structs/AsyncDefaults.html">AsyncDefaults</a>
              </li>
              <li class="nav-group-task">
                <a href="Structs/Expectation.html">Expectation</a>
              </li>
              <li class="nav-group-task">
                <a href="Structs/Expectation/Nil.html">– Nil</a>
              </li>
              <li class="nav-group-task">
                <a href="Structs/Expression.html">Expression</a>
              </li>
              <li class="nav-group-task">
                <a href="Structs/Predicate.html">Predicate</a>
              </li>
              <li class="nav-group-task">
                <a href="Structs/PredicateResult.html">PredicateResult</a>
              </li>
              <li class="nav-group-task">
                <a href="Structs/execTypesCountTuple.html">execTypesCountTuple</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Typealiases.html">Type Aliases</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Typealiases.html#/FileString">FileString</a>
              </li>
              <li class="nav-group-task">
                <a href="Typealiases.html#/s:6Nimble10FileStringa">FileString</a>
              </li>
              <li class="nav-group-task">
                <a href="Typealiases.html#/s:6Nimble14PredicateBlocka">PredicateBlock</a>
              </li>
            </ul>
          </li>
        </ul>
      </nav>
      <article class="main-content">
        <section>
          <section class="section">
            
            <h1 id='nimble' class='heading'>Nimble</h1>

<p><a href="https://github.com/Quick/Nimble/actions/workflows/ci-xcode.yml"><img src="https://github.com/Quick/Nimble/actions/workflows/ci-xcode.yml/badge.svg" alt="Build Status"></a>
<a href="https://cocoapods.org/pods/Nimble"><img src="https://img.shields.io/cocoapods/v/Nimble.svg" alt="CocoaPods"></a>
<a href="https://github.com/Carthage/Carthage"><img src="https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat" alt="Carthage Compatible"></a>
<a href="https://cocoapods.org/pods/Nimble"><img src="https://img.shields.io/cocoapods/p/Nimble.svg" alt="Platforms"></a></p>

<p>Use Nimble to express the expected outcomes of Swift
or Objective-C expressions. Inspired by
<a href="https://github.com/pivotal/cedar">Cedar</a>.</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>
<span class="nf">expect</span><span class="p">(</span><span class="mi">1</span> <span class="o">+</span> <span class="mi">1</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">equal</span><span class="p">(</span><span class="mi">2</span><span class="p">))</span>
<span class="nf">expect</span><span class="p">(</span><span class="mf">1.2</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beCloseTo</span><span class="p">(</span><span class="mf">1.1</span><span class="p">,</span> <span class="nv">within</span><span class="p">:</span> <span class="mf">0.1</span><span class="p">))</span>
<span class="nf">expect</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">2</span>
<span class="nf">expect</span><span class="p">(</span><span class="s">"seahorse"</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">contain</span><span class="p">(</span><span class="s">"sea"</span><span class="p">))</span>
<span class="nf">expect</span><span class="p">([</span><span class="s">"Atlantic"</span><span class="p">,</span> <span class="s">"Pacific"</span><span class="p">])</span><span class="o">.</span><span class="nf">toNot</span><span class="p">(</span><span class="nf">contain</span><span class="p">(</span><span class="s">"Mississippi"</span><span class="p">))</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">ocean</span><span class="o">.</span><span class="n">isClean</span><span class="p">)</span><span class="o">.</span><span class="nf">toEventually</span><span class="p">(</span><span class="nf">beTruthy</span><span class="p">())</span>
</code></pre>
<h1 id='how-to-use-nimble' class='heading'>How to Use Nimble</h1>

<!-- START doctoc generated TOC please keep comment here to allow auto update -->

<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

<p><strong>Table of Contents</strong>  <em>generated with <a href="https://github.com/thlorenz/doctoc">DocToc</a></em></p>

<ul>
<li><a href="#some-background-expressing-outcomes-using-assertions-in-xctest">Some Background: Expressing Outcomes Using Assertions in XCTest</a></li>
<li><a href="#nimble-expectations-using-expectto">Nimble: Expectations Using <code>expect(...).to</code></a>

<ul>
<li><a href="#custom-failure-messages">Custom Failure Messages</a></li>
<li><a href="#type-safety">Type Safety</a></li>
<li><a href="#operator-overloads">Operator Overloads</a></li>
<li><a href="#lazily-computed-values">Lazily Computed Values</a></li>
<li><a href="#c-primitives">C Primitives</a></li>
<li><a href="#asynchronous-expectations">Asynchronous Expectations</a></li>
<li><a href="#objective-c-support">Objective-C Support</a></li>
<li><a href="#disabling-objective-c-shorthand">Disabling Objective-C Shorthand</a></li>
</ul></li>
<li><a href="#built-in-matcher-functions">Built-in Matcher Functions</a>

<ul>
<li><a href="#type-checking">Type Checking</a></li>
<li><a href="#equivalence">Equivalence</a></li>
<li><a href="#identity">Identity</a></li>
<li><a href="#comparisons">Comparisons</a></li>
<li><a href="#typesclasses">Types/Classes</a></li>
<li><a href="#truthiness">Truthiness</a></li>
<li><a href="#swift-assertions">Swift Assertions</a></li>
<li><a href="#swift-error-handling">Swift Error Handling</a></li>
<li><a href="#exceptions">Exceptions</a></li>
<li><a href="#collection-membership">Collection Membership</a></li>
<li><a href="#strings">Strings</a></li>
<li><a href="#collection-elements">Collection Elements</a></li>
<li><a href="#collection-count">Collection Count</a></li>
<li><a href="#notifications">Notifications</a></li>
<li><a href="#result">Result</a></li>
<li><a href="#matching-a-value-to-any-of-a-group-of-matchers">Matching a value to any of a group of matchers</a></li>
<li><a href="#custom-validation">Custom Validation</a></li>
</ul></li>
<li><a href="#writing-your-own-matchers">Writing Your Own Matchers</a>

<ul>
<li><a href="#predicateresult">PredicateResult</a></li>
<li><a href="#lazy-evaluation">Lazy Evaluation</a></li>
<li><a href="#type-checking-via-swift-generics">Type Checking via Swift Generics</a></li>
<li><a href="#customizing-failure-messages">Customizing Failure Messages</a></li>
<li><a href="#basic-customization">Basic Customization</a></li>
<li><a href="#full-customization">Full Customization</a></li>
<li><a href="#supporting-objective-c">Supporting Objective-C</a></li>
<li><a href="#properly-handling-nil-in-objective-c-matchers">Properly Handling <code>nil</code> in Objective-C Matchers</a></li>
<li><a href="#migrating-from-the-old-matcher-api">Migrating from the Old Matcher API</a></li>
</ul></li>
<li><a href="#installing-nimble">Installing Nimble</a>

<ul>
<li><a href="#installing-nimble-as-a-submodule">Installing Nimble as a Submodule</a></li>
<li><a href="#installing-nimble-via-cocoapods">Installing Nimble via CocoaPods</a></li>
<li><a href="#using-nimble-without-xctest">Using Nimble without XCTest</a></li>
</ul></li>
</ul>

<!-- END doctoc generated TOC please keep comment here to allow auto update -->
<h1 id='some-background-expressing-outcomes-using-assertions-in-xctest' class='heading'>Some Background: Expressing Outcomes Using Assertions in XCTest</h1>

<p>Apple&rsquo;s Xcode includes the XCTest framework, which provides
assertion macros to test whether code behaves properly.
For example, to assert that <code>1 + 1 = 2</code>, XCTest has you write:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="kt">XCTAssertEqual</span><span class="p">(</span><span class="mi">1</span> <span class="o">+</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="s">"expected one plus one to equal two"</span><span class="p">)</span>
</code></pre>

<p>Or, in Objective-C:</p>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="n">XCTAssertEqual</span><span class="p">(</span><span class="mi">1</span> <span class="o">+</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="s">@"expected one plus one to equal two"</span><span class="p">);</span>
</code></pre>

<p>XCTest assertions have a couple of drawbacks:</p>

<ol>
<li><strong>Not enough macros.</strong> There&rsquo;s no easy way to assert that a string
contains a particular substring, or that a number is less than or
equal to another.</li>
<li><strong>It&rsquo;s hard to write asynchronous tests.</strong> XCTest forces you to write
a lot of boilerplate code.</li>
</ol>

<p>Nimble addresses these concerns.</p>
<h1 id='nimble-expectations-using-code-expect-to-code' class='heading'>Nimble: Expectations Using <code>expect(...).to</code></h1>

<p>Nimble allows you to express expectations using a natural,
easily understood language:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="kd">import</span> <span class="kt">Nimble</span>

<span class="nf">expect</span><span class="p">(</span><span class="n">seagull</span><span class="o">.</span><span class="n">squawk</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">equal</span><span class="p">(</span><span class="s">"Squee!"</span><span class="p">))</span>
</code></pre>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="k">@import</span> <span class="n">Nimble</span><span class="p">;</span>

<span class="n">expect</span><span class="p">(</span><span class="n">seagull</span><span class="p">.</span><span class="n">squawk</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">equal</span><span class="p">(</span><span class="s">@"Squee!"</span><span class="p">));</span>
</code></pre>

<blockquote>
<p>The <code>expect</code> function autocompletes to include <code>file:</code> and <code>line:</code>,
  but these parameters are optional. Use the default values to have
  Xcode highlight the correct line when an expectation is not met.</p>
</blockquote>

<p>To perform the opposite expectation&ndash;to assert something is <em>not</em>
equal&ndash;use <code>toNot</code> or <code>notTo</code>:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="kd">import</span> <span class="kt">Nimble</span>

<span class="nf">expect</span><span class="p">(</span><span class="n">seagull</span><span class="o">.</span><span class="n">squawk</span><span class="p">)</span><span class="o">.</span><span class="nf">toNot</span><span class="p">(</span><span class="nf">equal</span><span class="p">(</span><span class="s">"Oh, hello there!"</span><span class="p">))</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">seagull</span><span class="o">.</span><span class="n">squawk</span><span class="p">)</span><span class="o">.</span><span class="nf">notTo</span><span class="p">(</span><span class="nf">equal</span><span class="p">(</span><span class="s">"Oh, hello there!"</span><span class="p">))</span>
</code></pre>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="k">@import</span> <span class="n">Nimble</span><span class="p">;</span>

<span class="n">expect</span><span class="p">(</span><span class="n">seagull</span><span class="p">.</span><span class="n">squawk</span><span class="p">).</span><span class="n">toNot</span><span class="p">(</span><span class="n">equal</span><span class="p">(</span><span class="s">@"Oh, hello there!"</span><span class="p">));</span>
<span class="n">expect</span><span class="p">(</span><span class="n">seagull</span><span class="p">.</span><span class="n">squawk</span><span class="p">).</span><span class="n">notTo</span><span class="p">(</span><span class="n">equal</span><span class="p">(</span><span class="s">@"Oh, hello there!"</span><span class="p">));</span>
</code></pre>
<h2 id='custom-failure-messages' class='heading'>Custom Failure Messages</h2>

<p>Would you like to add more information to the test&rsquo;s failure messages? Use the <code>description</code> optional argument to add your own text:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="nf">expect</span><span class="p">(</span><span class="mi">1</span> <span class="o">+</span> <span class="mi">1</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">equal</span><span class="p">(</span><span class="mi">3</span><span class="p">))</span>
<span class="c1">// failed - expected to equal &lt;3&gt;, got &lt;2&gt;</span>

<span class="nf">expect</span><span class="p">(</span><span class="mi">1</span> <span class="o">+</span> <span class="mi">1</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">equal</span><span class="p">(</span><span class="mi">3</span><span class="p">),</span> <span class="nv">description</span><span class="p">:</span> <span class="s">"Make sure libKindergartenMath is loaded"</span><span class="p">)</span>
<span class="c1">// failed - Make sure libKindergartenMath is loaded</span>
<span class="c1">// expected to equal &lt;3&gt;, got &lt;2&gt;</span>
</code></pre>

<p>Or the *WithDescription version in Objective-C:</p>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="k">@import</span> <span class="n">Nimble</span><span class="p">;</span>

<span class="n">expect</span><span class="p">(</span><span class="err">@</span><span class="p">(</span><span class="mi">1</span><span class="o">+</span><span class="mi">1</span><span class="p">)).</span><span class="n">to</span><span class="p">(</span><span class="n">equal</span><span class="p">(</span><span class="mi">@3</span><span class="p">));</span>
<span class="c1">// failed - expected to equal &lt;3.0000&gt;, got &lt;2.0000&gt;</span>

<span class="n">expect</span><span class="p">(</span><span class="err">@</span><span class="p">(</span><span class="mi">1</span><span class="o">+</span><span class="mi">1</span><span class="p">)).</span><span class="n">toWithDescription</span><span class="p">(</span><span class="n">equal</span><span class="p">(</span><span class="mi">@3</span><span class="p">),</span> <span class="s">@"Make sure libKindergartenMath is loaded"</span><span class="p">);</span>
<span class="c1">// failed - Make sure libKindergartenMath is loaded</span>
<span class="c1">// expected to equal &lt;3.0000&gt;, got &lt;2.0000&gt;</span>
</code></pre>
<h2 id='type-safety' class='heading'>Type Safety</h2>

<p>Nimble makes sure you don&rsquo;t compare two types that don&rsquo;t match:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="c1">// Does not compile:</span>
<span class="nf">expect</span><span class="p">(</span><span class="mi">1</span> <span class="o">+</span> <span class="mi">1</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">equal</span><span class="p">(</span><span class="s">"Squee!"</span><span class="p">))</span>
</code></pre>

<blockquote>
<p>Nimble uses generics&ndash;only available in Swift&ndash;to ensure
  type correctness. That means type checking is
  not available when using Nimble in Objective-C. :sob:</p>
</blockquote>
<h2 id='operator-overloads' class='heading'>Operator Overloads</h2>

<p>Tired of so much typing? With Nimble, you can use overloaded operators
like <code>==</code> for equivalence, or <code>&gt;</code> for comparisons:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="c1">// Passes if squawk does not equal "Hi!":</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">seagull</span><span class="o">.</span><span class="n">squawk</span><span class="p">)</span> <span class="o">!=</span> <span class="s">"Hi!"</span>

<span class="c1">// Passes if 10 is greater than 2:</span>
<span class="nf">expect</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">2</span>
</code></pre>

<blockquote>
<p>Operator overloads are only available in Swift, so you won&rsquo;t be able
  to use this syntax in Objective-C. :broken_heart:</p>
</blockquote>
<h2 id='lazily-computed-values' class='heading'>Lazily Computed Values</h2>

<p>The <code>expect</code> function doesn&rsquo;t evaluate the value it&rsquo;s given until it&rsquo;s
time to match. So Nimble can test whether an expression raises an
exception once evaluated:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="c1">// Note: Swift currently doesn't have exceptions.</span>
<span class="c1">//       Only Objective-C code can raise exceptions</span>
<span class="c1">//       that Nimble will catch.</span>
<span class="c1">//       (see https://github.com/Quick/Nimble/issues/220#issuecomment-172667064)</span>
<span class="k">let</span> <span class="nv">exception</span> <span class="o">=</span> <span class="kt">NSException</span><span class="p">(</span>
    <span class="nv">name</span><span class="p">:</span> <span class="kt">NSInternalInconsistencyException</span><span class="p">,</span>
    <span class="nv">reason</span><span class="p">:</span> <span class="s">"Not enough fish in the sea."</span><span class="p">,</span>
    <span class="nv">userInfo</span><span class="p">:</span> <span class="p">[</span><span class="s">"something"</span><span class="p">:</span> <span class="s">"is fishy"</span><span class="p">])</span>
<span class="n">expect</span> <span class="p">{</span> <span class="n">exception</span><span class="o">.</span><span class="nf">raise</span><span class="p">()</span> <span class="p">}</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">raiseException</span><span class="p">())</span>

<span class="c1">// Also, you can customize raiseException to be more specific</span>
<span class="n">expect</span> <span class="p">{</span> <span class="n">exception</span><span class="o">.</span><span class="nf">raise</span><span class="p">()</span> <span class="p">}</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">raiseException</span><span class="p">(</span><span class="nv">named</span><span class="p">:</span> <span class="kt">NSInternalInconsistencyException</span><span class="p">))</span>
<span class="n">expect</span> <span class="p">{</span> <span class="n">exception</span><span class="o">.</span><span class="nf">raise</span><span class="p">()</span> <span class="p">}</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">raiseException</span><span class="p">(</span>
    <span class="nv">named</span><span class="p">:</span> <span class="kt">NSInternalInconsistencyException</span><span class="p">,</span>
    <span class="nv">reason</span><span class="p">:</span> <span class="s">"Not enough fish in the sea"</span><span class="p">))</span>
<span class="n">expect</span> <span class="p">{</span> <span class="n">exception</span><span class="o">.</span><span class="nf">raise</span><span class="p">()</span> <span class="p">}</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">raiseException</span><span class="p">(</span>
    <span class="nv">named</span><span class="p">:</span> <span class="kt">NSInternalInconsistencyException</span><span class="p">,</span>
    <span class="nv">reason</span><span class="p">:</span> <span class="s">"Not enough fish in the sea"</span><span class="p">,</span>
    <span class="nv">userInfo</span><span class="p">:</span> <span class="p">[</span><span class="s">"something"</span><span class="p">:</span> <span class="s">"is fishy"</span><span class="p">]))</span>
</code></pre>

<p>Objective-C works the same way, but you must use the <code>expectAction</code>
macro when making an expectation on an expression that has no return
value:</p>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="n">NSException</span> <span class="o">*</span><span class="n">exception</span> <span class="o">=</span> <span class="p">[</span><span class="n">NSException</span> <span class="nf">exceptionWithName</span><span class="p">:</span><span class="n">NSInternalInconsistencyException</span>
                                                 <span class="nl">reason:</span><span class="s">@"Not enough fish in the sea."</span>
                                               <span class="nl">userInfo:</span><span class="nb">nil</span><span class="p">];</span>
<span class="n">expectAction</span><span class="p">(</span><span class="o">^</span><span class="p">{</span> <span class="p">[</span><span class="n">exception</span> <span class="nf">raise</span><span class="p">];</span> <span class="p">}).</span><span class="n">to</span><span class="p">(</span><span class="n">raiseException</span><span class="p">());</span>

<span class="c1">// Use the property-block syntax to be more specific.</span>
<span class="n">expectAction</span><span class="p">(</span><span class="o">^</span><span class="p">{</span> <span class="p">[</span><span class="n">exception</span> <span class="nf">raise</span><span class="p">];</span> <span class="p">}).</span><span class="n">to</span><span class="p">(</span><span class="n">raiseException</span><span class="p">().</span><span class="n">named</span><span class="p">(</span><span class="n">NSInternalInconsistencyException</span><span class="p">));</span>
<span class="n">expectAction</span><span class="p">(</span><span class="o">^</span><span class="p">{</span> <span class="p">[</span><span class="n">exception</span> <span class="nf">raise</span><span class="p">];</span> <span class="p">}).</span><span class="n">to</span><span class="p">(</span><span class="n">raiseException</span><span class="p">().</span>
    <span class="n">named</span><span class="p">(</span><span class="n">NSInternalInconsistencyException</span><span class="p">).</span>
    <span class="n">reason</span><span class="p">(</span><span class="s">"Not enough fish in the sea"</span><span class="p">));</span>
<span class="n">expectAction</span><span class="p">(</span><span class="o">^</span><span class="p">{</span> <span class="p">[</span><span class="n">exception</span> <span class="nf">raise</span><span class="p">];</span> <span class="p">}).</span><span class="n">to</span><span class="p">(</span><span class="n">raiseException</span><span class="p">().</span>
    <span class="n">named</span><span class="p">(</span><span class="n">NSInternalInconsistencyException</span><span class="p">).</span>
    <span class="n">reason</span><span class="p">(</span><span class="s">"Not enough fish in the sea"</span><span class="p">).</span>
    <span class="n">userInfo</span><span class="p">(@{</span><span class="s">@"something"</span><span class="o">:</span> <span class="s">@"is fishy"</span><span class="p">}));</span>

<span class="c1">// You can also pass a block for custom matching of the raised exception</span>
<span class="n">expectAction</span><span class="p">(</span><span class="n">exception</span><span class="p">.</span><span class="n">raise</span><span class="p">()).</span><span class="n">to</span><span class="p">(</span><span class="n">raiseException</span><span class="p">().</span><span class="n">satisfyingBlock</span><span class="p">(</span><span class="o">^</span><span class="p">(</span><span class="n">NSException</span> <span class="o">*</span><span class="n">exception</span><span class="p">)</span> <span class="p">{</span>
    <span class="n">expect</span><span class="p">(</span><span class="n">exception</span><span class="p">.</span><span class="n">name</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">beginWith</span><span class="p">(</span><span class="n">NSInternalInconsistencyException</span><span class="p">));</span>
<span class="p">}));</span>
</code></pre>
<h2 id='c-primitives' class='heading'>C Primitives</h2>

<p>Some testing frameworks make it hard to test primitive C values.
In Nimble, it just works:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="k">let</span> <span class="nv">actual</span><span class="p">:</span> <span class="kt">CInt</span> <span class="o">=</span> <span class="mi">1</span>
<span class="k">let</span> <span class="nv">expectedValue</span><span class="p">:</span> <span class="kt">CInt</span> <span class="o">=</span> <span class="mi">1</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">equal</span><span class="p">(</span><span class="n">expectedValue</span><span class="p">))</span>
</code></pre>

<p>In fact, Nimble uses type inference, so you can write the above
without explicitly specifying both types:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="nf">expect</span><span class="p">(</span><span class="mi">1</span> <span class="k">as</span> <span class="kt">CInt</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">equal</span><span class="p">(</span><span class="mi">1</span><span class="p">))</span>
</code></pre>

<blockquote>
<p>In Objective-C, Nimble only supports Objective-C objects. To
  make expectations on primitive C values, wrap then in an object
  literal:</p>
</blockquote>
<pre class="highlight objective_c"><code><span class="n">expect</span><span class="p">(</span><span class="err">@</span><span class="p">(</span><span class="mi">1</span> <span class="o">+</span> <span class="mi">1</span><span class="p">)).</span><span class="n">to</span><span class="p">(</span><span class="n">equal</span><span class="p">(</span><span class="mi">@2</span><span class="p">));</span>
</code></pre>
<h2 id='asynchronous-expectations' class='heading'>Asynchronous Expectations</h2>

<p>In Nimble, it&rsquo;s easy to make expectations on values that are updated
asynchronously. Just use <code>toEventually</code> or <code>toEventuallyNot</code>:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>
<span class="kt">DispatchQueue</span><span class="o">.</span><span class="n">main</span><span class="o">.</span><span class="k">async</span> <span class="p">{</span>
    <span class="n">ocean</span><span class="o">.</span><span class="nf">add</span><span class="p">(</span><span class="s">"dolphins"</span><span class="p">)</span>
    <span class="n">ocean</span><span class="o">.</span><span class="nf">add</span><span class="p">(</span><span class="s">"whales"</span><span class="p">)</span>
<span class="p">}</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">ocean</span><span class="p">)</span><span class="o">.</span><span class="nf">toEventually</span><span class="p">(</span><span class="nf">contain</span><span class="p">(</span><span class="s">"dolphins"</span><span class="p">,</span> <span class="s">"whales"</span><span class="p">))</span>
</code></pre>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="n">dispatch_async</span><span class="p">(</span><span class="n">dispatch_get_main_queue</span><span class="p">(),</span> <span class="o">^</span><span class="p">{</span>
    <span class="p">[</span><span class="n">ocean</span> <span class="nf">add</span><span class="p">:</span><span class="s">@"dolphins"</span><span class="p">];</span>
    <span class="p">[</span><span class="n">ocean</span> <span class="nf">add</span><span class="p">:</span><span class="s">@"whales"</span><span class="p">];</span>
<span class="p">});</span>
<span class="n">expect</span><span class="p">(</span><span class="n">ocean</span><span class="p">).</span><span class="n">toEventually</span><span class="p">(</span><span class="n">contain</span><span class="p">(</span><span class="s">@"dolphins"</span><span class="p">,</span> <span class="s">@"whales"</span><span class="p">));</span>
</code></pre>

<p>Note: toEventually triggers its polls on the main thread. Blocking the main
thread will cause Nimble to stop the run loop. This can cause test pollution
for whatever incomplete code that was running on the main thread.  Blocking the
main thread can be caused by blocking IO, calls to sleep(), deadlocks, and
synchronous IPC.</p>

<p>In the above example, <code>ocean</code> is constantly re-evaluated. If it ever
contains dolphins and whales, the expectation passes. If <code>ocean</code> still
doesn&rsquo;t contain them, even after being continuously re-evaluated for one
whole second, the expectation fails.</p>

<p>You can also test that a value always or never matches throughout the length of the timeout. Use <code>toNever</code> and <code>toAlways</code> for this:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>
<span class="n">ocean</span><span class="o">.</span><span class="nf">add</span><span class="p">(</span><span class="s">"dolphins"</span><span class="p">)</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">ocean</span><span class="p">)</span><span class="o">.</span><span class="nf">toAlways</span><span class="p">(</span><span class="nf">contain</span><span class="p">(</span><span class="s">"dolphins"</span><span class="p">))</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">ocean</span><span class="p">)</span><span class="o">.</span><span class="nf">toNever</span><span class="p">(</span><span class="nf">contain</span><span class="p">(</span><span class="s">"hares"</span><span class="p">))</span>
</code></pre>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>
<span class="p">[</span><span class="n">ocean</span> <span class="nf">add</span><span class="p">:</span><span class="s">@"dolphins"</span><span class="p">]</span>
<span class="n">expect</span><span class="p">(</span><span class="n">ocean</span><span class="p">).</span><span class="n">toAlways</span><span class="p">(</span><span class="n">contain</span><span class="p">(</span><span class="s">@"dolphins"</span><span class="p">))</span>
<span class="n">expect</span><span class="p">(</span><span class="n">ocean</span><span class="p">).</span><span class="n">toNever</span><span class="p">(</span><span class="n">contain</span><span class="p">(</span><span class="s">@"hares"</span><span class="p">))</span>
</code></pre>

<p>Sometimes it takes more than a second for a value to update. In those
cases, use the <code>timeout</code> parameter:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="c1">// Waits three seconds for ocean to contain "starfish":</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">ocean</span><span class="p">)</span><span class="o">.</span><span class="nf">toEventually</span><span class="p">(</span><span class="nf">contain</span><span class="p">(</span><span class="s">"starfish"</span><span class="p">),</span> <span class="nv">timeout</span><span class="p">:</span> <span class="o">.</span><span class="nf">seconds</span><span class="p">(</span><span class="mi">3</span><span class="p">))</span>

<span class="c1">// Evaluate someValue every 0.2 seconds repeatedly until it equals 100, or fails if it timeouts after 5.5 seconds.</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">someValue</span><span class="p">)</span><span class="o">.</span><span class="nf">toEventually</span><span class="p">(</span><span class="nf">equal</span><span class="p">(</span><span class="mi">100</span><span class="p">),</span> <span class="nv">timeout</span><span class="p">:</span> <span class="o">.</span><span class="nf">milliseconds</span><span class="p">(</span><span class="mi">5500</span><span class="p">),</span> <span class="nv">pollInterval</span><span class="p">:</span> <span class="o">.</span><span class="nf">milliseconds</span><span class="p">(</span><span class="mi">200</span><span class="p">))</span>
</code></pre>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="c1">// Waits three seconds for ocean to contain "starfish":</span>
<span class="n">expect</span><span class="p">(</span><span class="n">ocean</span><span class="p">).</span><span class="n">withTimeout</span><span class="p">(</span><span class="mi">3</span><span class="p">).</span><span class="n">toEventually</span><span class="p">(</span><span class="n">contain</span><span class="p">(</span><span class="s">@"starfish"</span><span class="p">));</span>
</code></pre>

<p>You can also provide a callback by using the <code>waitUntil</code> function:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="n">waitUntil</span> <span class="p">{</span> <span class="n">done</span> <span class="k">in</span>
    <span class="n">ocean</span><span class="o">.</span><span class="n">goFish</span> <span class="p">{</span> <span class="n">success</span> <span class="k">in</span>
        <span class="nf">expect</span><span class="p">(</span><span class="n">success</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beTrue</span><span class="p">())</span>
        <span class="nf">done</span><span class="p">()</span>
    <span class="p">}</span>
<span class="p">}</span>
</code></pre>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="n">waitUntil</span><span class="p">(</span><span class="o">^</span><span class="p">(</span><span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">done</span><span class="p">)(</span><span class="kt">void</span><span class="p">)){</span>
    <span class="p">[</span><span class="n">ocean</span> <span class="nf">goFishWithHandler</span><span class="p">:</span><span class="o">^</span><span class="p">(</span><span class="n">BOOL</span> <span class="n">success</span><span class="p">){</span>
        <span class="n">expect</span><span class="p">(</span><span class="n">success</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">beTrue</span><span class="p">());</span>
        <span class="n">done</span><span class="p">();</span>
    <span class="p">}];</span>
<span class="p">});</span>
</code></pre>

<p><code>waitUntil</code> also optionally takes a timeout parameter:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="nf">waitUntil</span><span class="p">(</span><span class="nv">timeout</span><span class="p">:</span> <span class="o">.</span><span class="nf">seconds</span><span class="p">(</span><span class="mi">10</span><span class="p">))</span> <span class="p">{</span> <span class="n">done</span> <span class="k">in</span>
    <span class="n">ocean</span><span class="o">.</span><span class="n">goFish</span> <span class="p">{</span> <span class="n">success</span> <span class="k">in</span>
        <span class="nf">expect</span><span class="p">(</span><span class="n">success</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beTrue</span><span class="p">())</span>
        <span class="nf">done</span><span class="p">()</span>
    <span class="p">}</span>
<span class="p">}</span>
</code></pre>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="n">waitUntilTimeout</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="o">^</span><span class="p">(</span><span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">done</span><span class="p">)(</span><span class="kt">void</span><span class="p">)){</span>
    <span class="p">[</span><span class="n">ocean</span> <span class="nf">goFishWithHandler</span><span class="p">:</span><span class="o">^</span><span class="p">(</span><span class="n">BOOL</span> <span class="n">success</span><span class="p">){</span>
        <span class="n">expect</span><span class="p">(</span><span class="n">success</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">beTrue</span><span class="p">());</span>
        <span class="n">done</span><span class="p">();</span>
    <span class="p">}];</span>
<span class="p">});</span>
</code></pre>

<p>Note: <code>waitUntil</code> triggers its timeout code on the main thread. Blocking the main
thread will cause Nimble to stop the run loop to continue. This can cause test
pollution for whatever incomplete code that was running on the main thread.
Blocking the main thread can be caused by blocking IO, calls to sleep(),
deadlocks, and synchronous IPC.</p>

<p>In some cases (e.g. when running on slower machines) it can be useful to modify
the default timeout and poll interval values. This can be done as follows:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="c1">// Increase the global timeout to 5 seconds:</span>
<span class="kt">Nimble</span><span class="o">.</span><span class="kt">AsyncDefaults</span><span class="o">.</span><span class="n">timeout</span> <span class="o">=</span> <span class="o">.</span><span class="nf">seconds</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>

<span class="c1">// Slow the polling interval to 0.1 seconds:</span>
<span class="kt">Nimble</span><span class="o">.</span><span class="kt">AsyncDefaults</span><span class="o">.</span><span class="n">pollInterval</span> <span class="o">=</span> <span class="o">.</span><span class="nf">milliseconds</span><span class="p">(</span><span class="mi">100</span><span class="p">)</span>
</code></pre>
<h2 id='objective-c-support' class='heading'>Objective-C Support</h2>

<p>Nimble has full support for Objective-C. However, there are two things
to keep in mind when using Nimble in Objective-C:</p>

<ol>
<li>All parameters passed to the <code>expect</code> function, as well as matcher
functions like <code>equal</code>, must be Objective-C objects or can be converted into
an <code>NSObject</code> equivalent:</li>
</ol>
<pre class="highlight objective_c"><code>   <span class="c1">// Objective-C</span>

   <span class="k">@import</span> <span class="n">Nimble</span><span class="p">;</span>

   <span class="n">expect</span><span class="p">(</span><span class="err">@</span><span class="p">(</span><span class="mi">1</span> <span class="o">+</span> <span class="mi">1</span><span class="p">)).</span><span class="n">to</span><span class="p">(</span><span class="n">equal</span><span class="p">(</span><span class="mi">@2</span><span class="p">));</span>
   <span class="n">expect</span><span class="p">(</span><span class="s">@"Hello world"</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">contain</span><span class="p">(</span><span class="s">@"world"</span><span class="p">));</span>

   <span class="c1">// Boxed as NSNumber *</span>
   <span class="n">expect</span><span class="p">(</span><span class="mi">2</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">equal</span><span class="p">(</span><span class="mi">2</span><span class="p">));</span>
   <span class="n">expect</span><span class="p">(</span><span class="mi">1</span><span class="p">.</span><span class="mi">2</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">beLessThan</span><span class="p">(</span><span class="mi">2</span><span class="p">.</span><span class="mi">0</span><span class="p">));</span>
   <span class="n">expect</span><span class="p">(</span><span class="nb">true</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">beTruthy</span><span class="p">());</span>

   <span class="c1">// Boxed as NSString *</span>
   <span class="n">expect</span><span class="p">(</span><span class="s">"Hello world"</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">equal</span><span class="p">(</span><span class="s">"Hello world"</span><span class="p">));</span>

   <span class="c1">// Boxed as NSRange</span>
   <span class="n">expect</span><span class="p">(</span><span class="n">NSMakeRange</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">10</span><span class="p">)).</span><span class="n">to</span><span class="p">(</span><span class="n">equal</span><span class="p">(</span><span class="n">NSMakeRange</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">10</span><span class="p">)));</span>
</code></pre>

<ol>
<li>To make an expectation on an expression that does not return a value,
such as <code>-[NSException raise]</code>, use <code>expectAction</code> instead of
<code>expect</code>:</li>
</ol>
<pre class="highlight objective_c"><code>   <span class="c1">// Objective-C</span>

   <span class="n">expectAction</span><span class="p">(</span><span class="o">^</span><span class="p">{</span> <span class="p">[</span><span class="n">exception</span> <span class="nf">raise</span><span class="p">];</span> <span class="p">}).</span><span class="n">to</span><span class="p">(</span><span class="n">raiseException</span><span class="p">());</span>
</code></pre>

<p>The following types are currently converted to an <code>NSObject</code> type:</p>

<ul>
<li><strong>C Numeric types</strong> are converted to <code>NSNumber *</code></li>
<li><code>NSRange</code> is converted to <code>NSValue *</code></li>
<li><code>char *</code> is converted to <code>NSString *</code></li>
</ul>

<p>For the following matchers:</p>

<ul>
<li><code>equal</code></li>
<li><code>beGreaterThan</code></li>
<li><code>beGreaterThanOrEqual</code></li>
<li><code>beLessThan</code></li>
<li><code>beLessThanOrEqual</code></li>
<li><code>beCloseTo</code></li>
<li><code>beTrue</code></li>
<li><code>beFalse</code></li>
<li><code>beTruthy</code></li>
<li><code>beFalsy</code></li>
<li><code>haveCount</code></li>
</ul>

<p>If you would like to see more, <a href="https://github.com/Quick/Nimble/issues">file an issue</a>.</p>
<h2 id='disabling-objective-c-shorthand' class='heading'>Disabling Objective-C Shorthand</h2>

<p>Nimble provides a shorthand for expressing expectations using the
<code>expect</code> function. To disable this shorthand in Objective-C, define the
<code>NIMBLE_DISABLE_SHORT_SYNTAX</code> macro somewhere in your code before
importing Nimble:</p>
<pre class="highlight objective_c"><code><span class="cp">#define NIMBLE_DISABLE_SHORT_SYNTAX 1
</span>
<span class="k">@import</span> <span class="n">Nimble</span><span class="p">;</span>

<span class="n">NMB_expect</span><span class="p">(</span><span class="o">^</span><span class="p">{</span> <span class="k">return</span> <span class="n">seagull</span><span class="p">.</span><span class="n">squawk</span><span class="p">;</span> <span class="p">},</span> <span class="n">__FILE__</span><span class="p">,</span> <span class="n">__LINE__</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">NMB_equal</span><span class="p">(</span><span class="s">@"Squee!"</span><span class="p">));</span>
</code></pre>

<blockquote>
<p>Disabling the shorthand is useful if you&rsquo;re testing functions with
  names that conflict with Nimble functions, such as <code>expect</code> or
  <code>equal</code>. If that&rsquo;s not the case, there&rsquo;s no point in disabling the
  shorthand.</p>
</blockquote>
<h1 id='built-in-matcher-functions' class='heading'>Built-in Matcher Functions</h1>

<p>Nimble includes a wide variety of matcher functions.</p>
<h2 id='type-checking' class='heading'>Type Checking</h2>

<p>Nimble supports checking the type membership of any kind of object, whether
Objective-C conformant or not:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="kd">protocol</span> <span class="kt">SomeProtocol</span><span class="p">{}</span>
<span class="kd">class</span> <span class="kt">SomeClassConformingToProtocol</span><span class="p">:</span> <span class="kt">SomeProtocol</span><span class="p">{}</span>
<span class="kd">struct</span> <span class="kt">SomeStructConformingToProtocol</span><span class="p">:</span> <span class="kt">SomeProtocol</span><span class="p">{}</span>

<span class="c1">// The following tests pass</span>
<span class="nf">expect</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beAKindOf</span><span class="p">(</span><span class="kt">Int</span><span class="o">.</span><span class="k">self</span><span class="p">))</span>
<span class="nf">expect</span><span class="p">(</span><span class="s">"turtle"</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beAKindOf</span><span class="p">(</span><span class="kt">String</span><span class="o">.</span><span class="k">self</span><span class="p">))</span>

<span class="k">let</span> <span class="nv">classObject</span> <span class="o">=</span> <span class="kt">SomeClassConformingToProtocol</span><span class="p">()</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">classObject</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beAKindOf</span><span class="p">(</span><span class="kt">SomeProtocol</span><span class="o">.</span><span class="k">self</span><span class="p">))</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">classObject</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beAKindOf</span><span class="p">(</span><span class="kt">SomeClassConformingToProtocol</span><span class="o">.</span><span class="k">self</span><span class="p">))</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">classObject</span><span class="p">)</span><span class="o">.</span><span class="nf">toNot</span><span class="p">(</span><span class="nf">beAKindOf</span><span class="p">(</span><span class="kt">SomeStructConformingToProtocol</span><span class="o">.</span><span class="k">self</span><span class="p">))</span>

<span class="k">let</span> <span class="nv">structObject</span> <span class="o">=</span> <span class="kt">SomeStructConformingToProtocol</span><span class="p">()</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">structObject</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beAKindOf</span><span class="p">(</span><span class="kt">SomeProtocol</span><span class="o">.</span><span class="k">self</span><span class="p">))</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">structObject</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beAKindOf</span><span class="p">(</span><span class="kt">SomeStructConformingToProtocol</span><span class="o">.</span><span class="k">self</span><span class="p">))</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">structObject</span><span class="p">)</span><span class="o">.</span><span class="nf">toNot</span><span class="p">(</span><span class="nf">beAKindOf</span><span class="p">(</span><span class="kt">SomeClassConformingToProtocol</span><span class="o">.</span><span class="k">self</span><span class="p">))</span>
</code></pre>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="c1">// The following tests pass</span>
<span class="n">NSMutableArray</span> <span class="o">*</span><span class="n">array</span> <span class="o">=</span> <span class="p">[</span><span class="n">NSMutableArray</span> <span class="nf">array</span><span class="p">];</span>
<span class="n">expect</span><span class="p">(</span><span class="n">array</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">beAKindOf</span><span class="p">([</span><span class="n">NSArray</span> <span class="nf">class</span><span class="p">]));</span>
<span class="n">expect</span><span class="p">(</span><span class="mi">@1</span><span class="p">).</span><span class="n">toNot</span><span class="p">(</span><span class="n">beAKindOf</span><span class="p">([</span><span class="n">NSNull</span> <span class="nf">class</span><span class="p">]));</span>
</code></pre>

<p>Objects can be tested for their exact types using the <code>beAnInstanceOf</code> matcher:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="kd">protocol</span> <span class="kt">SomeProtocol</span><span class="p">{}</span>
<span class="kd">class</span> <span class="kt">SomeClassConformingToProtocol</span><span class="p">:</span> <span class="kt">SomeProtocol</span><span class="p">{}</span>
<span class="kd">struct</span> <span class="kt">SomeStructConformingToProtocol</span><span class="p">:</span> <span class="kt">SomeProtocol</span><span class="p">{}</span>

<span class="c1">// Unlike the 'beKindOf' matcher, the 'beAnInstanceOf' matcher only</span>
<span class="c1">// passes if the object is the EXACT type requested. The following</span>
<span class="c1">// tests pass -- note its behavior when working in an inheritance hierarchy.</span>
<span class="nf">expect</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beAnInstanceOf</span><span class="p">(</span><span class="kt">Int</span><span class="o">.</span><span class="k">self</span><span class="p">))</span>
<span class="nf">expect</span><span class="p">(</span><span class="s">"turtle"</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beAnInstanceOf</span><span class="p">(</span><span class="kt">String</span><span class="o">.</span><span class="k">self</span><span class="p">))</span>

<span class="k">let</span> <span class="nv">classObject</span> <span class="o">=</span> <span class="kt">SomeClassConformingToProtocol</span><span class="p">()</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">classObject</span><span class="p">)</span><span class="o">.</span><span class="nf">toNot</span><span class="p">(</span><span class="nf">beAnInstanceOf</span><span class="p">(</span><span class="kt">SomeProtocol</span><span class="o">.</span><span class="k">self</span><span class="p">))</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">classObject</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beAnInstanceOf</span><span class="p">(</span><span class="kt">SomeClassConformingToProtocol</span><span class="o">.</span><span class="k">self</span><span class="p">))</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">classObject</span><span class="p">)</span><span class="o">.</span><span class="nf">toNot</span><span class="p">(</span><span class="nf">beAnInstanceOf</span><span class="p">(</span><span class="kt">SomeStructConformingToProtocol</span><span class="o">.</span><span class="k">self</span><span class="p">))</span>

<span class="k">let</span> <span class="nv">structObject</span> <span class="o">=</span> <span class="kt">SomeStructConformingToProtocol</span><span class="p">()</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">structObject</span><span class="p">)</span><span class="o">.</span><span class="nf">toNot</span><span class="p">(</span><span class="nf">beAnInstanceOf</span><span class="p">(</span><span class="kt">SomeProtocol</span><span class="o">.</span><span class="k">self</span><span class="p">))</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">structObject</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beAnInstanceOf</span><span class="p">(</span><span class="kt">SomeStructConformingToProtocol</span><span class="o">.</span><span class="k">self</span><span class="p">))</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">structObject</span><span class="p">)</span><span class="o">.</span><span class="nf">toNot</span><span class="p">(</span><span class="nf">beAnInstanceOf</span><span class="p">(</span><span class="kt">SomeClassConformingToProtocol</span><span class="o">.</span><span class="k">self</span><span class="p">))</span>
</code></pre>
<h2 id='equivalence' class='heading'>Equivalence</h2>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="c1">// Passes if 'actual' is equivalent to 'expected':</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">equal</span><span class="p">(</span><span class="n">expected</span><span class="p">))</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span> <span class="o">==</span> <span class="n">expected</span>

<span class="c1">// Passes if 'actual' is not equivalent to 'expected':</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">toNot</span><span class="p">(</span><span class="nf">equal</span><span class="p">(</span><span class="n">expected</span><span class="p">))</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span> <span class="o">!=</span> <span class="n">expected</span>
</code></pre>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="c1">// Passes if 'actual' is equivalent to 'expected':</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">equal</span><span class="p">(</span><span class="n">expected</span><span class="p">))</span>

<span class="c1">// Passes if 'actual' is not equivalent to 'expected':</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">toNot</span><span class="p">(</span><span class="n">equal</span><span class="p">(</span><span class="n">expected</span><span class="p">))</span>
</code></pre>

<p>Values must be <code>Equatable</code>, <code>Comparable</code>, or subclasses of <code>NSObject</code>.
<code>equal</code> will always fail when used to compare one or more <code>nil</code> values.</p>
<h2 id='identity' class='heading'>Identity</h2>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="c1">// Passes if 'actual' has the same pointer address as 'expected':</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beIdenticalTo</span><span class="p">(</span><span class="n">expected</span><span class="p">))</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span> <span class="o">===</span> <span class="n">expected</span>

<span class="c1">// Passes if 'actual' does not have the same pointer address as 'expected':</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">toNot</span><span class="p">(</span><span class="nf">beIdenticalTo</span><span class="p">(</span><span class="n">expected</span><span class="p">))</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span> <span class="o">!==</span> <span class="n">expected</span>
</code></pre>

<p>It is important to remember that <code>beIdenticalTo</code> only makes sense when comparing
types with reference semantics, which have a notion of identity. In Swift, 
that means types that are defined as a <code>class</code>. </p>

<p>This matcher will not work when comparing types with value semantics such as
those defined as a <code>struct</code> or <code>enum</code>. If you need to compare two value types,
consider what it means for instances of your type to be identical. This may mean
comparing individual properties or, if it makes sense to do so, conforming your type 
to <code>Equatable</code> and using Nimble&rsquo;s equivalence matchers instead.</p>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="c1">// Passes if 'actual' has the same pointer address as 'expected':</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">beIdenticalTo</span><span class="p">(</span><span class="n">expected</span><span class="p">));</span>

<span class="c1">// Passes if 'actual' does not have the same pointer address as 'expected':</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">toNot</span><span class="p">(</span><span class="n">beIdenticalTo</span><span class="p">(</span><span class="n">expected</span><span class="p">));</span>
</code></pre>
<h2 id='comparisons' class='heading'>Comparisons</h2>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beLessThan</span><span class="p">(</span><span class="n">expected</span><span class="p">))</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span> <span class="o">&lt;</span> <span class="n">expected</span>

<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beLessThanOrEqualTo</span><span class="p">(</span><span class="n">expected</span><span class="p">))</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span> <span class="o">&lt;=</span> <span class="n">expected</span>

<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beGreaterThan</span><span class="p">(</span><span class="n">expected</span><span class="p">))</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span> <span class="o">&gt;</span> <span class="n">expected</span>

<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beGreaterThanOrEqualTo</span><span class="p">(</span><span class="n">expected</span><span class="p">))</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span> <span class="o">&gt;=</span> <span class="n">expected</span>
</code></pre>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">beLessThan</span><span class="p">(</span><span class="n">expected</span><span class="p">));</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">beLessThanOrEqualTo</span><span class="p">(</span><span class="n">expected</span><span class="p">));</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">beGreaterThan</span><span class="p">(</span><span class="n">expected</span><span class="p">));</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">beGreaterThanOrEqualTo</span><span class="p">(</span><span class="n">expected</span><span class="p">));</span>
</code></pre>

<blockquote>
<p>Values given to the comparison matchers above must implement
  <code>Comparable</code>.</p>
</blockquote>

<p>Because of how computers represent floating point numbers, assertions
that two floating point numbers be equal will sometimes fail. To express
that two numbers should be close to one another within a certain margin
of error, use <code>beCloseTo</code>:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beCloseTo</span><span class="p">(</span><span class="n">expected</span><span class="p">,</span> <span class="nv">within</span><span class="p">:</span> <span class="n">delta</span><span class="p">))</span>
</code></pre>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">beCloseTo</span><span class="p">(</span><span class="n">expected</span><span class="p">).</span><span class="n">within</span><span class="p">(</span><span class="n">delta</span><span class="p">));</span>
</code></pre>

<p>For example, to assert that <code>10.01</code> is close to <code>10</code>, you can write:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="nf">expect</span><span class="p">(</span><span class="mf">10.01</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beCloseTo</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="nv">within</span><span class="p">:</span> <span class="mf">0.1</span><span class="p">))</span>
</code></pre>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="n">expect</span><span class="p">(</span><span class="err">@</span><span class="p">(</span><span class="mi">10</span><span class="p">.</span><span class="mo">01</span><span class="p">)).</span><span class="n">to</span><span class="p">(</span><span class="n">beCloseTo</span><span class="p">(</span><span class="mi">@10</span><span class="p">).</span><span class="n">within</span><span class="p">(</span><span class="mi">0</span><span class="p">.</span><span class="mi">1</span><span class="p">));</span>
</code></pre>

<p>There is also an operator shortcut available in Swift:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span> <span class="err">≈</span> <span class="n">expected</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span> <span class="err">≈</span> <span class="p">(</span><span class="n">expected</span><span class="p">,</span> <span class="n">delta</span><span class="p">)</span>

</code></pre>

<p>(Type <kbd>option</kbd>+<kbd>x</kbd> to get <code>≈</code> on a U.S. keyboard)</p>

<p>The former version uses the default delta of 0.0001. Here is yet another way to do this:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span> <span class="err">≈</span> <span class="n">expected</span> <span class="err">±</span> <span class="n">delta</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span> <span class="o">==</span> <span class="n">expected</span> <span class="err">±</span> <span class="n">delta</span>

</code></pre>

<p>(Type <kbd>option</kbd>+<kbd>shift</kbd>+<kbd>=</kbd> to get <code>±</code> on a U.S. keyboard)</p>

<p>If you are comparing arrays of floating point numbers, you&rsquo;ll find the following useful:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="nf">expect</span><span class="p">([</span><span class="mf">0.0</span><span class="p">,</span> <span class="mf">2.0</span><span class="p">])</span> <span class="err">≈</span> <span class="p">[</span><span class="mf">0.0001</span><span class="p">,</span> <span class="mf">2.0001</span><span class="p">]</span>
<span class="nf">expect</span><span class="p">([</span><span class="mf">0.0</span><span class="p">,</span> <span class="mf">2.0</span><span class="p">])</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beCloseTo</span><span class="p">([</span><span class="mf">0.1</span><span class="p">,</span> <span class="mf">2.1</span><span class="p">],</span> <span class="nv">within</span><span class="p">:</span> <span class="mf">0.1</span><span class="p">))</span>

</code></pre>

<blockquote>
<p>Values given to the <code>beCloseTo</code> matcher must conform to <code>FloatingPoint</code>.</p>
</blockquote>
<h2 id='types-classes' class='heading'>Types/Classes</h2>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="c1">// Passes if 'instance' is an instance of 'aClass':</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">instance</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beAnInstanceOf</span><span class="p">(</span><span class="n">aClass</span><span class="p">))</span>

<span class="c1">// Passes if 'instance' is an instance of 'aClass' or any of its subclasses:</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">instance</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beAKindOf</span><span class="p">(</span><span class="n">aClass</span><span class="p">))</span>
</code></pre>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="c1">// Passes if 'instance' is an instance of 'aClass':</span>
<span class="n">expect</span><span class="p">(</span><span class="n">instance</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">beAnInstanceOf</span><span class="p">(</span><span class="n">aClass</span><span class="p">));</span>

<span class="c1">// Passes if 'instance' is an instance of 'aClass' or any of its subclasses:</span>
<span class="n">expect</span><span class="p">(</span><span class="n">instance</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">beAKindOf</span><span class="p">(</span><span class="n">aClass</span><span class="p">));</span>
</code></pre>

<blockquote>
<p>Instances must be Objective-C objects: subclasses of <code>NSObject</code>,
  or Swift objects bridged to Objective-C with the <code>@objc</code> prefix.</p>
</blockquote>

<p>For example, to assert that <code>dolphin</code> is a kind of <code>Mammal</code>:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="nf">expect</span><span class="p">(</span><span class="n">dolphin</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beAKindOf</span><span class="p">(</span><span class="kt">Mammal</span><span class="p">))</span>
</code></pre>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="n">expect</span><span class="p">(</span><span class="n">dolphin</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">beAKindOf</span><span class="p">([</span><span class="n">Mammal</span> <span class="nf">class</span><span class="p">]));</span>
</code></pre>

<blockquote>
<p><code>beAnInstanceOf</code> uses the <code>-[NSObject isMemberOfClass:]</code> method to
  test membership. <code>beAKindOf</code> uses <code>-[NSObject isKindOfClass:]</code>.</p>
</blockquote>
<h2 id='truthiness' class='heading'>Truthiness</h2>
<pre class="highlight swift"><code><span class="c1">// Passes if 'actual' is not nil, true, or an object with a boolean value of true:</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beTruthy</span><span class="p">())</span>

<span class="c1">// Passes if 'actual' is only true (not nil or an object conforming to Boolean true):</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beTrue</span><span class="p">())</span>

<span class="c1">// Passes if 'actual' is nil, false, or an object with a boolean value of false:</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beFalsy</span><span class="p">())</span>

<span class="c1">// Passes if 'actual' is only false (not nil or an object conforming to Boolean false):</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beFalse</span><span class="p">())</span>

<span class="c1">// Passes if 'actual' is nil:</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beNil</span><span class="p">())</span>
</code></pre>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="c1">// Passes if 'actual' is not nil, true, or an object with a boolean value of true:</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">beTruthy</span><span class="p">());</span>

<span class="c1">// Passes if 'actual' is only true (not nil or an object conforming to Boolean true):</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">beTrue</span><span class="p">());</span>

<span class="c1">// Passes if 'actual' is nil, false, or an object with a boolean value of false:</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">beFalsy</span><span class="p">());</span>

<span class="c1">// Passes if 'actual' is only false (not nil or an object conforming to Boolean false):</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">beFalse</span><span class="p">());</span>

<span class="c1">// Passes if 'actual' is nil:</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">beNil</span><span class="p">());</span>
</code></pre>
<h2 id='swift-assertions' class='heading'>Swift Assertions</h2>

<p>If you&rsquo;re using Swift, you can use the <code>throwAssertion</code> matcher to check if an assertion is thrown (e.g. <code>fatalError()</code>). This is made possible by <a href="https://github.com/mattgallagher">@mattgallagher</a>&rsquo;s <a href="https://github.com/mattgallagher/CwlPreconditionTesting">CwlPreconditionTesting</a> library.</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="c1">// Passes if 'somethingThatThrows()' throws an assertion, </span>
<span class="c1">// such as by calling 'fatalError()' or if a precondition fails:</span>
<span class="n">expect</span> <span class="p">{</span> <span class="k">try</span> <span class="nf">somethingThatThrows</span><span class="p">()</span> <span class="p">}</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">throwAssertion</span><span class="p">())</span>
<span class="n">expect</span> <span class="p">{</span> <span class="p">()</span> <span class="o">-&gt;</span> <span class="kt">Void</span> <span class="k">in</span> <span class="nf">fatalError</span><span class="p">()</span> <span class="p">}</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">throwAssertion</span><span class="p">())</span>
<span class="n">expect</span> <span class="p">{</span> <span class="nf">precondition</span><span class="p">(</span><span class="kc">false</span><span class="p">)</span> <span class="p">}</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">throwAssertion</span><span class="p">())</span>

<span class="c1">// Passes if throwing an NSError is not equal to throwing an assertion:</span>
<span class="n">expect</span> <span class="p">{</span> <span class="k">throw</span> <span class="kt">NSError</span><span class="p">(</span><span class="nv">domain</span><span class="p">:</span> <span class="s">"test"</span><span class="p">,</span> <span class="nv">code</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span> <span class="nv">userInfo</span><span class="p">:</span> <span class="kc">nil</span><span class="p">)</span> <span class="p">}</span><span class="o">.</span><span class="nf">toNot</span><span class="p">(</span><span class="nf">throwAssertion</span><span class="p">())</span>

<span class="c1">// Passes if the code after the precondition check is not run:</span>
<span class="k">var</span> <span class="nv">reachedPoint1</span> <span class="o">=</span> <span class="kc">false</span>
<span class="k">var</span> <span class="nv">reachedPoint2</span> <span class="o">=</span> <span class="kc">false</span>
<span class="n">expect</span> <span class="p">{</span>
    <span class="n">reachedPoint1</span> <span class="o">=</span> <span class="kc">true</span>
    <span class="nf">precondition</span><span class="p">(</span><span class="kc">false</span><span class="p">,</span> <span class="s">"condition message"</span><span class="p">)</span>
    <span class="n">reachedPoint2</span> <span class="o">=</span> <span class="kc">true</span>
<span class="p">}</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">throwAssertion</span><span class="p">())</span>

<span class="nf">expect</span><span class="p">(</span><span class="n">reachedPoint1</span><span class="p">)</span> <span class="o">==</span> <span class="kc">true</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">reachedPoint2</span><span class="p">)</span> <span class="o">==</span> <span class="kc">false</span>
</code></pre>

<p>Notes:</p>

<ul>
<li>This feature is only available in Swift.</li>
<li>The tvOS simulator is supported, but using a different mechanism, requiring you to turn off the <code>Debug executable</code> scheme setting for your tvOS scheme&rsquo;s Test configuration.</li>
</ul>
<h2 id='swift-error-handling' class='heading'>Swift Error Handling</h2>

<p>You can use the <code>throwError</code> matcher to check if an error is thrown.</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="c1">// Passes if 'somethingThatThrows()' throws an 'Error':</span>
<span class="n">expect</span> <span class="p">{</span> <span class="k">try</span> <span class="nf">somethingThatThrows</span><span class="p">()</span> <span class="p">}</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">throwError</span><span class="p">())</span>

<span class="c1">// Passes if 'somethingThatThrows()' throws an error within a particular domain:</span>
<span class="n">expect</span> <span class="p">{</span> <span class="k">try</span> <span class="nf">somethingThatThrows</span><span class="p">()</span> <span class="p">}</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="n">throwError</span> <span class="p">{</span> <span class="p">(</span><span class="nv">error</span><span class="p">:</span> <span class="kt">Error</span><span class="p">)</span> <span class="k">in</span>
    <span class="nf">expect</span><span class="p">(</span><span class="n">error</span><span class="o">.</span><span class="n">_domain</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">equal</span><span class="p">(</span><span class="kt">NSCocoaErrorDomain</span><span class="p">))</span>
<span class="p">})</span>

<span class="c1">// Passes if 'somethingThatThrows()' throws a particular error enum case:</span>
<span class="n">expect</span> <span class="p">{</span> <span class="k">try</span> <span class="nf">somethingThatThrows</span><span class="p">()</span> <span class="p">}</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">throwError</span><span class="p">(</span><span class="kt">NSCocoaError</span><span class="o">.</span><span class="kt">PropertyListReadCorruptError</span><span class="p">))</span>

<span class="c1">// Passes if 'somethingThatThrows()' throws an error of a particular type:</span>
<span class="n">expect</span> <span class="p">{</span> <span class="k">try</span> <span class="nf">somethingThatThrows</span><span class="p">()</span> <span class="p">}</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">throwError</span><span class="p">(</span><span class="nv">errorType</span><span class="p">:</span> <span class="kt">NimbleError</span><span class="o">.</span><span class="k">self</span><span class="p">))</span>
</code></pre>

<p>When working directly with <code>Error</code> values, using the <code>matchError</code> matcher
allows you to perform certain checks on the error itself without having to
explicitly cast the error.</p>

<p>The <code>matchError</code> matcher allows you to check whether or not the error:</p>

<ul>
<li>is the same <em>type</em> of error you are expecting.</li>
<li>represents a particular error value that you are expecting.</li>
</ul>

<p>This can be useful when using <code>Result</code> or <code>Promise</code> types, for example.</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="k">let</span> <span class="nv">actual</span><span class="p">:</span> <span class="kt">Error</span> <span class="o">=</span> <span class="o">...</span>

<span class="c1">// Passes if 'actual' represents any error value from the NimbleErrorEnum type:</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">matchError</span><span class="p">(</span><span class="kt">NimbleErrorEnum</span><span class="o">.</span><span class="k">self</span><span class="p">))</span>

<span class="c1">// Passes if 'actual' represents the case 'timeout' from the NimbleErrorEnum type:</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">matchError</span><span class="p">(</span><span class="kt">NimbleErrorEnum</span><span class="o">.</span><span class="n">timeout</span><span class="p">))</span>

<span class="c1">// Passes if 'actual' contains an NSError equal to the one provided:</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">matchError</span><span class="p">(</span><span class="kt">NSError</span><span class="p">(</span><span class="nv">domain</span><span class="p">:</span> <span class="s">"err"</span><span class="p">,</span> <span class="nv">code</span><span class="p">:</span> <span class="mi">123</span><span class="p">,</span> <span class="nv">userInfo</span><span class="p">:</span> <span class="kc">nil</span><span class="p">)))</span>
</code></pre>

<p>Note: This feature is only available in Swift.</p>
<h2 id='exceptions' class='heading'>Exceptions</h2>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="c1">// Passes if 'actual', when evaluated, raises an exception:</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">raiseException</span><span class="p">())</span>

<span class="c1">// Passes if 'actual' raises an exception with the given name:</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">raiseException</span><span class="p">(</span><span class="nv">named</span><span class="p">:</span> <span class="n">name</span><span class="p">))</span>

<span class="c1">// Passes if 'actual' raises an exception with the given name and reason:</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">raiseException</span><span class="p">(</span><span class="nv">named</span><span class="p">:</span> <span class="n">name</span><span class="p">,</span> <span class="nv">reason</span><span class="p">:</span> <span class="n">reason</span><span class="p">))</span>

<span class="c1">// Passes if 'actual' raises an exception which passes expectations defined in the given closure:</span>
<span class="c1">// (in this case, if the exception's name begins with "a r")</span>
<span class="n">expect</span> <span class="p">{</span> <span class="n">exception</span><span class="o">.</span><span class="nf">raise</span><span class="p">()</span> <span class="p">}</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="n">raiseException</span> <span class="p">{</span> <span class="p">(</span><span class="nv">exception</span><span class="p">:</span> <span class="kt">NSException</span><span class="p">)</span> <span class="k">in</span>
    <span class="nf">expect</span><span class="p">(</span><span class="n">exception</span><span class="o">.</span><span class="n">name</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beginWith</span><span class="p">(</span><span class="s">"a r"</span><span class="p">))</span>
<span class="p">})</span>
</code></pre>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="c1">// Passes if 'actual', when evaluated, raises an exception:</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">raiseException</span><span class="p">())</span>

<span class="c1">// Passes if 'actual' raises an exception with the given name</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">raiseException</span><span class="p">().</span><span class="n">named</span><span class="p">(</span><span class="n">name</span><span class="p">))</span>

<span class="c1">// Passes if 'actual' raises an exception with the given name and reason:</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">raiseException</span><span class="p">().</span><span class="n">named</span><span class="p">(</span><span class="n">name</span><span class="p">).</span><span class="n">reason</span><span class="p">(</span><span class="n">reason</span><span class="p">))</span>

<span class="c1">// Passes if 'actual' raises an exception and it passes expectations defined in the given block:</span>
<span class="c1">// (in this case, if name begins with "a r")</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">raiseException</span><span class="p">().</span><span class="n">satisfyingBlock</span><span class="p">(</span><span class="o">^</span><span class="p">(</span><span class="n">NSException</span> <span class="o">*</span><span class="n">exception</span><span class="p">)</span> <span class="p">{</span>
    <span class="n">expect</span><span class="p">(</span><span class="n">exception</span><span class="p">.</span><span class="n">name</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">beginWith</span><span class="p">(</span><span class="s">@"a r"</span><span class="p">));</span>
<span class="p">}));</span>
</code></pre>

<p>Note: Swift currently doesn&rsquo;t have exceptions (see <a href="https://github.com/Quick/Nimble/issues/220#issuecomment-172667064">#220</a>). 
Only Objective-C code can raise exceptions that Nimble will catch.</p>
<h2 id='collection-membership' class='heading'>Collection Membership</h2>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="c1">// Passes if all of the expected values are members of 'actual':</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">contain</span><span class="p">(</span><span class="n">expected</span><span class="o">...</span><span class="p">))</span>

<span class="c1">// Passes if 'actual' is empty (i.e. it contains no elements):</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beEmpty</span><span class="p">())</span>
</code></pre>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="c1">// Passes if expected is a member of 'actual':</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">contain</span><span class="p">(</span><span class="n">expected</span><span class="p">));</span>

<span class="c1">// Passes if 'actual' is empty (i.e. it contains no elements):</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">beEmpty</span><span class="p">());</span>
</code></pre>

<blockquote>
<p>In Swift <code>contain</code> takes any number of arguments. The expectation
  passes if all of them are members of the collection. In Objective-C,
  <code>contain</code> only takes one argument <a href="https://github.com/Quick/Nimble/issues/27">for now</a>.</p>
</blockquote>

<p>For example, to assert that a list of sea creature names contains
&ldquo;dolphin&rdquo; and &ldquo;starfish&rdquo;:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="nf">expect</span><span class="p">([</span><span class="s">"whale"</span><span class="p">,</span> <span class="s">"dolphin"</span><span class="p">,</span> <span class="s">"starfish"</span><span class="p">])</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">contain</span><span class="p">(</span><span class="s">"dolphin"</span><span class="p">,</span> <span class="s">"starfish"</span><span class="p">))</span>
</code></pre>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="n">expect</span><span class="p">(@[</span><span class="s">@"whale"</span><span class="p">,</span> <span class="s">@"dolphin"</span><span class="p">,</span> <span class="s">@"starfish"</span><span class="p">]).</span><span class="n">to</span><span class="p">(</span><span class="n">contain</span><span class="p">(</span><span class="s">@"dolphin"</span><span class="p">));</span>
<span class="n">expect</span><span class="p">(@[</span><span class="s">@"whale"</span><span class="p">,</span> <span class="s">@"dolphin"</span><span class="p">,</span> <span class="s">@"starfish"</span><span class="p">]).</span><span class="n">to</span><span class="p">(</span><span class="n">contain</span><span class="p">(</span><span class="s">@"starfish"</span><span class="p">));</span>
</code></pre>

<blockquote>
<p><code>contain</code> and <code>beEmpty</code> expect collections to be instances of
  <code>NSArray</code>, <code>NSSet</code>, or a Swift collection composed of <code>Equatable</code> elements.</p>
</blockquote>

<p>To test whether a set of elements is present at the beginning or end of
an ordered collection, use <code>beginWith</code> and <code>endWith</code>:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="c1">// Passes if the elements in expected appear at the beginning of 'actual':</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beginWith</span><span class="p">(</span><span class="n">expected</span><span class="o">...</span><span class="p">))</span>

<span class="c1">// Passes if the the elements in expected come at the end of 'actual':</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">endWith</span><span class="p">(</span><span class="n">expected</span><span class="o">...</span><span class="p">))</span>
</code></pre>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="c1">// Passes if the elements in expected appear at the beginning of 'actual':</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">beginWith</span><span class="p">(</span><span class="n">expected</span><span class="p">));</span>

<span class="c1">// Passes if the the elements in expected come at the end of 'actual':</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">endWith</span><span class="p">(</span><span class="n">expected</span><span class="p">));</span>
</code></pre>

<blockquote>
<p><code>beginWith</code> and <code>endWith</code> expect collections to be instances of
  <code>NSArray</code>, or ordered Swift collections composed of <code>Equatable</code>
  elements.</p>
</blockquote>

<p>Like <code>contain</code>, in Objective-C <code>beginWith</code> and <code>endWith</code> only support
  a single argument <a href="https://github.com/Quick/Nimble/issues/27">for now</a>.</p>

<p>For code that returns collections of complex objects without a strict
ordering, there is the <code>containElementSatisfying</code> matcher:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="kd">struct</span> <span class="kt">Turtle</span> <span class="p">{</span>
    <span class="k">let</span> <span class="nv">color</span><span class="p">:</span> <span class="kt">String</span>
<span class="p">}</span>

<span class="k">let</span> <span class="nv">turtles</span><span class="p">:</span> <span class="p">[</span><span class="kt">Turtle</span><span class="p">]</span> <span class="o">=</span> <span class="nf">functionThatReturnsSomeTurtlesInAnyOrder</span><span class="p">()</span>

<span class="c1">// This set of matchers passes regardless of whether the array is </span>
<span class="c1">// [{color: "blue"}, {color: "green"}] or [{color: "green"}, {color: "blue"}]:</span>

<span class="nf">expect</span><span class="p">(</span><span class="n">turtles</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">containElementSatisfying</span><span class="p">({</span> <span class="n">turtle</span> <span class="k">in</span>
    <span class="k">return</span> <span class="n">turtle</span><span class="o">.</span><span class="n">color</span> <span class="o">==</span> <span class="s">"green"</span>
<span class="p">}))</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">turtles</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">containElementSatisfying</span><span class="p">({</span> <span class="n">turtle</span> <span class="k">in</span>
    <span class="k">return</span> <span class="n">turtle</span><span class="o">.</span><span class="n">color</span> <span class="o">==</span> <span class="s">"blue"</span>
<span class="p">},</span> <span class="s">"that is a turtle with color 'blue'"</span><span class="p">))</span>

<span class="c1">// The second matcher will incorporate the provided string in the error message</span>
<span class="c1">// should it fail</span>
</code></pre>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="k">@interface</span> <span class="nc">Turtle</span> <span class="p">:</span> <span class="nc">NSObject</span>
<span class="k">@property</span> <span class="p">(</span><span class="n">nonatomic</span><span class="p">,</span> <span class="n">readonly</span><span class="p">,</span> <span class="n">nonnull</span><span class="p">)</span> <span class="n">NSString</span> <span class="o">*</span><span class="n">color</span><span class="p">;</span>
<span class="k">@end</span>

<span class="k">@implementation</span> <span class="nc">Turtle</span> 
<span class="k">@end</span>

<span class="n">NSArray</span><span class="o">&lt;</span><span class="n">Turtle</span> <span class="o">*&gt;</span> <span class="o">*</span> <span class="n">__nonnull</span> <span class="n">turtles</span> <span class="o">=</span> <span class="n">functionThatReturnsSomeTurtlesInAnyOrder</span><span class="p">();</span>

<span class="c1">// This set of matchers passes regardless of whether the array is </span>
<span class="c1">// [{color: "blue"}, {color: "green"}] or [{color: "green"}, {color: "blue"}]:</span>

<span class="n">expect</span><span class="p">(</span><span class="n">turtles</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">containElementSatisfying</span><span class="p">(</span><span class="o">^</span><span class="n">BOOL</span><span class="p">(</span><span class="n">id</span> <span class="n">__nonnull</span> <span class="n">object</span><span class="p">)</span> <span class="p">{</span>
    <span class="k">return</span> <span class="p">[[</span><span class="n">turtle</span> <span class="nf">color</span><span class="p">]</span> <span class="nf">isEqualToString</span><span class="p">:</span><span class="s">@"green"</span><span class="p">];</span>
<span class="p">}));</span>
<span class="n">expect</span><span class="p">(</span><span class="n">turtles</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">containElementSatisfying</span><span class="p">(</span><span class="o">^</span><span class="n">BOOL</span><span class="p">(</span><span class="n">id</span> <span class="n">__nonnull</span> <span class="n">object</span><span class="p">)</span> <span class="p">{</span>
    <span class="k">return</span> <span class="p">[[</span><span class="n">turtle</span> <span class="nf">color</span><span class="p">]</span> <span class="nf">isEqualToString</span><span class="p">:</span><span class="s">@"blue"</span><span class="p">];</span>
<span class="p">}));</span>
</code></pre>

<p>For asserting on if the given <code>Comparable</code> value is inside of a <code>Range</code>, use the <code>beWithin</code> matcher.</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="c1">// Passes if 5 is within the range 1 through 10, inclusive</span>
<span class="nf">expect</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beWithin</span><span class="p">(</span><span class="mi">1</span><span class="o">...</span><span class="mi">10</span><span class="p">))</span>

<span class="c1">// Passes if 5 is not within the range 2 through 4.</span>
<span class="nf">expect</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span><span class="o">.</span><span class="nf">toNot</span><span class="p">(</span><span class="nf">beWithin</span><span class="p">(</span><span class="mi">2</span><span class="o">..&lt;</span><span class="mi">5</span><span class="p">))</span>
</code></pre>
<h2 id='strings' class='heading'>Strings</h2>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="c1">// Passes if 'actual' contains 'substring':</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">contain</span><span class="p">(</span><span class="n">substring</span><span class="p">))</span>

<span class="c1">// Passes if 'actual' begins with 'prefix':</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beginWith</span><span class="p">(</span><span class="k">prefix</span><span class="p">))</span>

<span class="c1">// Passes if 'actual' ends with 'suffix':</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">endWith</span><span class="p">(</span><span class="n">suffix</span><span class="p">))</span>

<span class="c1">// Passes if 'actual' represents the empty string, "":</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beEmpty</span><span class="p">())</span>

<span class="c1">// Passes if 'actual' matches the regular expression defined in 'expected':</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">match</span><span class="p">(</span><span class="n">expected</span><span class="p">))</span>
</code></pre>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="c1">// Passes if 'actual' contains 'substring':</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">contain</span><span class="p">(</span><span class="n">expected</span><span class="p">));</span>

<span class="c1">// Passes if 'actual' begins with 'prefix':</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">beginWith</span><span class="p">(</span><span class="n">prefix</span><span class="p">));</span>

<span class="c1">// Passes if 'actual' ends with 'suffix':</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">endWith</span><span class="p">(</span><span class="n">suffix</span><span class="p">));</span>

<span class="c1">// Passes if 'actual' represents the empty string, "":</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">beEmpty</span><span class="p">());</span>

<span class="c1">// Passes if 'actual' matches the regular expression defined in 'expected':</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">match</span><span class="p">(</span><span class="n">expected</span><span class="p">))</span>
</code></pre>
<h2 id='collection-elements' class='heading'>Collection Elements</h2>

<p>Nimble provides a means to check that all elements of a collection pass a given expectation.</p>
<h3 id='swift' class='heading'>Swift</h3>

<p>In Swift, the collection must be an instance of a type conforming to
<code>Sequence</code>.</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="c1">// Providing a custom function:</span>
<span class="nf">expect</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">])</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="n">allPass</span> <span class="p">{</span> <span class="nv">$0</span> <span class="o">&lt;</span> <span class="mi">5</span> <span class="p">})</span>

<span class="c1">// Composing the expectation with another matcher:</span>
<span class="nf">expect</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">])</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">allPass</span><span class="p">(</span><span class="nf">beLessThan</span><span class="p">(</span><span class="mi">5</span><span class="p">)))</span>
</code></pre>
<h3 id='objective-c' class='heading'>Objective-C</h3>

<p>In Objective-C, the collection must be an instance of a type which implements
the <code>NSFastEnumeration</code> protocol, and whose elements are instances of a type
which subclasses <code>NSObject</code>.</p>

<p>Additionally, unlike in Swift, there is no override to specify a custom
matcher function.</p>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="n">expect</span><span class="p">(@[</span><span class="mi">@1</span><span class="p">,</span> <span class="mi">@2</span><span class="p">,</span> <span class="mi">@3</span><span class="p">,</span> <span class="mi">@4</span><span class="p">]).</span><span class="n">to</span><span class="p">(</span><span class="n">allPass</span><span class="p">(</span><span class="n">beLessThan</span><span class="p">(</span><span class="mi">@5</span><span class="p">)));</span>
</code></pre>
<h2 id='collection-count' class='heading'>Collection Count</h2>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="c1">// Passes if 'actual' contains the 'expected' number of elements:</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">haveCount</span><span class="p">(</span><span class="n">expected</span><span class="p">))</span>

<span class="c1">// Passes if 'actual' does _not_ contain the 'expected' number of elements:</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">notTo</span><span class="p">(</span><span class="nf">haveCount</span><span class="p">(</span><span class="n">expected</span><span class="p">))</span>
</code></pre>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="c1">// Passes if 'actual' contains the 'expected' number of elements:</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">haveCount</span><span class="p">(</span><span class="n">expected</span><span class="p">))</span>

<span class="c1">// Passes if 'actual' does _not_ contain the 'expected' number of elements:</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">notTo</span><span class="p">(</span><span class="n">haveCount</span><span class="p">(</span><span class="n">expected</span><span class="p">))</span>
</code></pre>

<p>For Swift, the actual value must be an instance of a type conforming to <code>Collection</code>.
For example, instances of <code>Array</code>, <code>Dictionary</code>, or <code>Set</code>.</p>

<p>For Objective-C, the actual value must be one of the following classes, or their subclasses:</p>

<ul>
<li><code>NSArray</code>,</li>
<li><code>NSDictionary</code>,</li>
<li><code>NSSet</code>, or</li>
<li><code>NSHashTable</code>.</li>
</ul>
<h2 id='notifications' class='heading'>Notifications</h2>
<pre class="highlight swift"><code><span class="c1">// Swift</span>
<span class="k">let</span> <span class="nv">testNotification</span> <span class="o">=</span> <span class="kt">Notification</span><span class="p">(</span><span class="nv">name</span><span class="p">:</span> <span class="kt">Notification</span><span class="o">.</span><span class="kt">Name</span><span class="p">(</span><span class="s">"Foo"</span><span class="p">),</span> <span class="nv">object</span><span class="p">:</span> <span class="kc">nil</span><span class="p">)</span>

<span class="c1">// Passes if the closure in expect { ... } posts a notification to the default</span>
<span class="c1">// notification center.</span>
<span class="n">expect</span> <span class="p">{</span>
    <span class="kt">NotificationCenter</span><span class="o">.</span><span class="k">default</span><span class="o">.</span><span class="nf">post</span><span class="p">(</span><span class="n">testNotification</span><span class="p">)</span>
<span class="p">}</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">postNotifications</span><span class="p">(</span><span class="nf">equal</span><span class="p">([</span><span class="n">testNotification</span><span class="p">])))</span>

<span class="c1">// Passes if the closure in expect { ... } posts a notification to a given</span>
<span class="c1">// notification center</span>
<span class="k">let</span> <span class="nv">notificationCenter</span> <span class="o">=</span> <span class="kt">NotificationCenter</span><span class="p">()</span>
<span class="n">expect</span> <span class="p">{</span>
    <span class="n">notificationCenter</span><span class="o">.</span><span class="nf">post</span><span class="p">(</span><span class="n">testNotification</span><span class="p">)</span>
<span class="p">}</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">postNotifications</span><span class="p">(</span><span class="nf">equal</span><span class="p">([</span><span class="n">testNotification</span><span class="p">]),</span> <span class="nv">from</span><span class="p">:</span> <span class="n">notificationCenter</span><span class="p">))</span>

<span class="c1">// Passes if the closure in expect { ... } posts a notification with the provided names to a given</span>
<span class="c1">// notification center. Make sure to use this when running tests on Catalina, </span>
<span class="c1">// using DistributedNotificationCenter as there is currently no way </span>
<span class="c1">// of observing notifications without providing specific names.</span>
<span class="k">let</span> <span class="nv">distributedNotificationCenter</span> <span class="o">=</span> <span class="kt">DistributedNotificationCenter</span><span class="p">()</span>
<span class="n">expect</span> <span class="p">{</span>
    <span class="n">distributedNotificationCenter</span><span class="o">.</span><span class="nf">post</span><span class="p">(</span><span class="n">testNotification</span><span class="p">)</span>
<span class="p">}</span><span class="o">.</span><span class="nf">toEventually</span><span class="p">(</span><span class="nf">postDistributedNotifications</span><span class="p">(</span><span class="nf">equal</span><span class="p">([</span><span class="n">testNotification</span><span class="p">]),</span>
                                  <span class="nv">from</span><span class="p">:</span> <span class="n">distributedNotificationCenter</span><span class="p">,</span>
                                  <span class="nv">names</span><span class="p">:</span> <span class="p">[</span><span class="n">testNotification</span><span class="o">.</span><span class="n">name</span><span class="p">]))</span>
</code></pre>

<blockquote>
<p>This matcher is only available in Swift.</p>
</blockquote>
<h2 id='result' class='heading'>Result</h2>
<pre class="highlight swift"><code><span class="c1">// Swift</span>
<span class="k">let</span> <span class="nv">aResult</span><span class="p">:</span> <span class="kt">Result</span><span class="o">&lt;</span><span class="kt">String</span><span class="p">,</span> <span class="kt">Error</span><span class="o">&gt;</span> <span class="o">=</span> <span class="o">.</span><span class="nf">success</span><span class="p">(</span><span class="s">"Hooray"</span><span class="p">)</span> 

<span class="c1">// passes if result is .success</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">aResult</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beSuccess</span><span class="p">())</span> 

<span class="c1">// passes if result value is .success and validates Success value</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">aResult</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="n">beSuccess</span> <span class="p">{</span> <span class="n">value</span> <span class="k">in</span>
    <span class="nf">expect</span><span class="p">(</span><span class="n">value</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">equal</span><span class="p">(</span><span class="s">"Hooray"</span><span class="p">))</span>
<span class="p">})</span>


<span class="kd">enum</span> <span class="kt">AnError</span><span class="p">:</span> <span class="kt">Error</span> <span class="p">{</span>
    <span class="k">case</span> <span class="n">somethingHappened</span>
<span class="p">}</span>
<span class="k">let</span> <span class="nv">otherResult</span><span class="p">:</span> <span class="kt">Result</span><span class="o">&lt;</span><span class="kt">String</span><span class="p">,</span> <span class="kt">AnError</span><span class="o">&gt;</span> <span class="o">=</span> <span class="o">.</span><span class="nf">failure</span><span class="p">(</span><span class="o">.</span><span class="n">somethingHappened</span><span class="p">)</span> 

<span class="c1">// passes if result is .failure</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">otherResult</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beFailure</span><span class="p">())</span> 

<span class="c1">// passes if result value is .failure and validates error</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">otherResult</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="n">beFailure</span> <span class="p">{</span> <span class="n">error</span> <span class="k">in</span>
    <span class="nf">expect</span><span class="p">(</span><span class="n">error</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">matchError</span><span class="p">(</span><span class="kt">AnError</span><span class="o">.</span><span class="n">somethingHappened</span><span class="p">))</span>
<span class="p">})</span> 
</code></pre>

<blockquote>
<p>This matcher is only available in Swift.</p>
</blockquote>
<h2 id='matching-a-value-to-any-of-a-group-of-matchers' class='heading'>Matching a value to any of a group of matchers</h2>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="c1">// passes if actual is either less than 10 or greater than 20</span>
<span class="nf">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">satisfyAnyOf</span><span class="p">(</span><span class="nf">beLessThan</span><span class="p">(</span><span class="mi">10</span><span class="p">),</span> <span class="nf">beGreaterThan</span><span class="p">(</span><span class="mi">20</span><span class="p">)))</span>

<span class="c1">// can include any number of matchers -- the following will pass</span>
<span class="c1">// **be careful** -- too many matchers can be the sign of an unfocused test</span>
<span class="nf">expect</span><span class="p">(</span><span class="mi">6</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">satisfyAnyOf</span><span class="p">(</span><span class="nf">equal</span><span class="p">(</span><span class="mi">2</span><span class="p">),</span> <span class="nf">equal</span><span class="p">(</span><span class="mi">3</span><span class="p">),</span> <span class="nf">equal</span><span class="p">(</span><span class="mi">4</span><span class="p">),</span> <span class="nf">equal</span><span class="p">(</span><span class="mi">5</span><span class="p">),</span> <span class="nf">equal</span><span class="p">(</span><span class="mi">6</span><span class="p">),</span> <span class="nf">equal</span><span class="p">(</span><span class="mi">7</span><span class="p">)))</span>

<span class="c1">// in Swift you also have the option to use the || operator to achieve a similar function</span>
<span class="nf">expect</span><span class="p">(</span><span class="mi">82</span><span class="p">)</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">beLessThan</span><span class="p">(</span><span class="mi">50</span><span class="p">)</span> <span class="o">||</span> <span class="nf">beGreaterThan</span><span class="p">(</span><span class="mi">80</span><span class="p">))</span>
</code></pre>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="c1">// passes if actual is either less than 10 or greater than 20</span>
<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">satisfyAnyOf</span><span class="p">(</span><span class="n">beLessThan</span><span class="p">(</span><span class="mi">@10</span><span class="p">),</span> <span class="n">beGreaterThan</span><span class="p">(</span><span class="mi">@20</span><span class="p">)))</span>

<span class="c1">// can include any number of matchers -- the following will pass</span>
<span class="c1">// **be careful** -- too many matchers can be the sign of an unfocused test</span>
<span class="n">expect</span><span class="p">(</span><span class="mi">@6</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">satisfyAnyOf</span><span class="p">(</span><span class="n">equal</span><span class="p">(</span><span class="mi">@2</span><span class="p">),</span> <span class="n">equal</span><span class="p">(</span><span class="mi">@3</span><span class="p">),</span> <span class="n">equal</span><span class="p">(</span><span class="mi">@4</span><span class="p">),</span> <span class="n">equal</span><span class="p">(</span><span class="mi">@5</span><span class="p">),</span> <span class="n">equal</span><span class="p">(</span><span class="mi">@6</span><span class="p">),</span> <span class="n">equal</span><span class="p">(</span><span class="mi">@7</span><span class="p">)))</span>
</code></pre>

<p>Note: This matcher allows you to chain any number of matchers together. This provides flexibility,
      but if you find yourself chaining many matchers together in one test, consider whether you
      could instead refactor that single test into multiple, more precisely focused tests for
      better coverage.</p>
<h2 id='custom-validation' class='heading'>Custom Validation</h2>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="c1">// passes if .succeeded is returned from the closure</span>
<span class="n">expect</span> <span class="p">{</span>
    <span class="k">guard</span> <span class="k">case</span> <span class="o">.</span><span class="n">enumCaseWithAssociatedValueThatIDontCareAbout</span> <span class="o">=</span> <span class="n">actual</span> <span class="k">else</span> <span class="p">{</span>
        <span class="k">return</span> <span class="o">.</span><span class="nf">failed</span><span class="p">(</span><span class="nv">reason</span><span class="p">:</span> <span class="s">"wrong enum case"</span><span class="p">)</span>
    <span class="p">}</span>

    <span class="k">return</span> <span class="o">.</span><span class="n">succeeded</span>
<span class="p">}</span><span class="o">.</span><span class="nf">to</span><span class="p">(</span><span class="nf">succeed</span><span class="p">())</span>

<span class="c1">// passes if .failed is returned from the closure</span>
<span class="n">expect</span> <span class="p">{</span>
    <span class="k">guard</span> <span class="k">case</span> <span class="o">.</span><span class="n">enumCaseWithAssociatedValueThatIDontCareAbout</span> <span class="o">=</span> <span class="n">actual</span> <span class="k">else</span> <span class="p">{</span>
        <span class="k">return</span> <span class="o">.</span><span class="nf">failed</span><span class="p">(</span><span class="nv">reason</span><span class="p">:</span> <span class="s">"wrong enum case"</span><span class="p">)</span>
    <span class="p">}</span>

    <span class="k">return</span> <span class="o">.</span><span class="n">succeeded</span>
<span class="p">}</span><span class="o">.</span><span class="nf">notTo</span><span class="p">(</span><span class="nf">succeed</span><span class="p">())</span>
</code></pre>

<p>The <code>String</code> provided with <code>.failed()</code> is shown when the test fails.</p>

<p>When using <code>toEventually()</code> be careful not to make state changes or run process intensive code since this closure will be ran many times.</p>
<h1 id='writing-your-own-matchers' class='heading'>Writing Your Own Matchers</h1>

<p>In Nimble, matchers are Swift functions that take an expected
value and return a <code><a href="Structs/Predicate.html">Predicate</a></code> closure. Take <code>equal</code>, for example:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="kd">public</span> <span class="kd">func</span> <span class="n">equal</span><span class="o">&lt;</span><span class="kt">T</span><span class="p">:</span> <span class="kt">Equatable</span><span class="o">&gt;</span><span class="p">(</span><span class="nv">expectedValue</span><span class="p">:</span> <span class="kt">T</span><span class="p">?)</span> <span class="o">-&gt;</span> <span class="kt">Predicate</span><span class="o">&lt;</span><span class="kt">T</span><span class="o">&gt;</span> <span class="p">{</span>
    <span class="c1">// Can be shortened to:</span>
    <span class="c1">//   Predicate { actual in  ... }</span>
    <span class="c1">//</span>
    <span class="c1">// But shown with types here for clarity.</span>
    <span class="k">return</span> <span class="kt">Predicate</span> <span class="p">{</span> <span class="p">(</span><span class="nv">actualExpression</span><span class="p">:</span> <span class="kt">Expression</span><span class="o">&lt;</span><span class="kt">T</span><span class="o">&gt;</span><span class="p">)</span> <span class="k">throws</span> <span class="o">-&gt;</span> <span class="kt">PredicateResult</span> <span class="k">in</span>
        <span class="k">let</span> <span class="nv">msg</span> <span class="o">=</span> <span class="kt">ExpectationMessage</span><span class="o">.</span><span class="nf">expectedActualValueTo</span><span class="p">(</span><span class="s">"equal &lt;</span><span class="se">\(</span><span class="n">expectedValue</span><span class="se">)</span><span class="s">&gt;"</span><span class="p">)</span>
        <span class="k">if</span> <span class="k">let</span> <span class="nv">actualValue</span> <span class="o">=</span> <span class="k">try</span> <span class="n">actualExpression</span><span class="o">.</span><span class="nf">evaluate</span><span class="p">()</span> <span class="p">{</span>
            <span class="k">return</span> <span class="kt">PredicateResult</span><span class="p">(</span>
                <span class="nv">bool</span><span class="p">:</span> <span class="n">actualValue</span> <span class="o">==</span> <span class="n">expectedValue</span><span class="o">!</span><span class="p">,</span>
                <span class="nv">message</span><span class="p">:</span> <span class="n">msg</span>
            <span class="p">)</span>
        <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
            <span class="k">return</span> <span class="kt">PredicateResult</span><span class="p">(</span>
                <span class="nv">status</span><span class="p">:</span> <span class="o">.</span><span class="n">fail</span><span class="p">,</span>
                <span class="nv">message</span><span class="p">:</span> <span class="n">msg</span><span class="o">.</span><span class="nf">appendedBeNilHint</span><span class="p">()</span>
            <span class="p">)</span>
        <span class="p">}</span>
    <span class="p">}</span>
<span class="p">}</span>
</code></pre>

<p>The return value of a <code><a href="Structs/Predicate.html">Predicate</a></code> closure is a <code><a href="Structs/PredicateResult.html">PredicateResult</a></code> that indicates
whether the actual value matches the expectation and what error message to
display on failure.</p>

<blockquote>
<p>The actual <code>equal</code> matcher function does not match when
  <code>expected</code> are nil; the example above has been edited for brevity.</p>
</blockquote>

<p>Since matchers are just Swift functions, you can define them anywhere:
at the top of your test file, in a file shared by all of your tests, or
in an Xcode project you distribute to others.</p>

<blockquote>
<p>If you write a matcher you think everyone can use, consider adding it
  to Nimble&rsquo;s built-in set of matchers by sending a pull request! Or
  distribute it yourself via GitHub.</p>
</blockquote>

<p>For examples of how to write your own matchers, just check out the
<a href="https://github.com/Quick/Nimble/tree/main/Sources/Nimble/Matchers"><code>Matchers</code> directory</a>
to see how Nimble&rsquo;s built-in set of matchers are implemented. You can
also check out the tips below.</p>
<h2 id='predicateresult' class='heading'>PredicateResult</h2>

<p><code><a href="Structs/PredicateResult.html">PredicateResult</a></code> is the return struct that <code><a href="Structs/Predicate.html">Predicate</a></code> return to indicate
success and failure. A <code><a href="Structs/PredicateResult.html">PredicateResult</a></code> is made up of two values:
<code><a href="Enums/PredicateStatus.html">PredicateStatus</a></code> and <code><a href="Enums/ExpectationMessage.html">ExpectationMessage</a></code>.</p>

<p>Instead of a boolean, <code><a href="Enums/PredicateStatus.html">PredicateStatus</a></code> captures a trinary set of values:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="kd">public</span> <span class="kd">enum</span> <span class="kt">PredicateStatus</span> <span class="p">{</span>
<span class="c1">// The predicate "passes" with the given expression</span>
<span class="c1">// eg - expect(1).to(equal(1))</span>
<span class="k">case</span> <span class="n">matches</span>

<span class="c1">// The predicate "fails" with the given expression</span>
<span class="c1">// eg - expect(1).toNot(equal(1))</span>
<span class="k">case</span> <span class="n">doesNotMatch</span>

<span class="c1">// The predicate never "passes" with the given expression, even if negated</span>
<span class="c1">// eg - expect(nil as Int?).toNot(equal(1))</span>
<span class="k">case</span> <span class="n">fail</span>

<span class="c1">// ...</span>
<span class="p">}</span>
</code></pre>

<p>Meanwhile, <code><a href="Enums/ExpectationMessage.html">ExpectationMessage</a></code> provides messaging semantics for error reporting.</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="kd">public</span> <span class="kd">indirect</span> <span class="kd">enum</span> <span class="kt">ExpectationMessage</span> <span class="p">{</span>
<span class="c1">// Emits standard error message:</span>
<span class="c1">// eg - "expected to &lt;string&gt;, got &lt;actual&gt;"</span>
<span class="k">case</span> <span class="nf">expectedActualValueTo</span><span class="p">(</span><span class="cm">/* message: */</span> <span class="kt">String</span><span class="p">)</span>

<span class="c1">// Allows any free-form message</span>
<span class="c1">// eg - "&lt;string&gt;"</span>
<span class="k">case</span> <span class="nf">fail</span><span class="p">(</span><span class="cm">/* message: */</span> <span class="kt">String</span><span class="p">)</span>

<span class="c1">// ...</span>
<span class="p">}</span>
</code></pre>

<p>Predicates should usually depend on either <code>.expectedActualValueTo(..)</code> or
<code>.fail(..)</code> when reporting errors. Special cases can be used for the other enum
cases.</p>

<p>Finally, if your Predicate utilizes other Predicates, you can utilize
<code>.appended(details:)</code> and <code>.appended(message:)</code> methods to annotate an existing
error with more details.</p>

<p>A common message to append is failing on nils. For that, <code>.appendedBeNilHint()</code>
can be used.</p>
<h2 id='lazy-evaluation' class='heading'>Lazy Evaluation</h2>

<p><code>actualExpression</code> is a lazy, memoized closure around the value provided to the
<code>expect</code> function. The expression can either be a closure or a value directly
passed to <code><a href="Functions.html#/s:6Nimble6expect4file4line_AA11ExpectationVyxGSS_SuxSgyKXAtlF">expect(...)</a></code>. In order to determine whether that value matches,
custom matchers should call <code>actualExpression.evaluate()</code>:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="kd">public</span> <span class="kd">func</span> <span class="n">beNil</span><span class="o">&lt;</span><span class="kt">T</span><span class="o">&gt;</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="kt">Predicate</span><span class="o">&lt;</span><span class="kt">T</span><span class="o">&gt;</span> <span class="p">{</span>
    <span class="c1">// Predicate.simpleNilable(..) automatically generates ExpectationMessage for</span>
    <span class="c1">// us based on the string we provide to it. Also, the 'Nilable' postfix indicates</span>
    <span class="c1">// that this Predicate supports matching against nil actualExpressions, instead of</span>
    <span class="c1">// always resulting in a PredicateStatus.fail result -- which is true for</span>
    <span class="c1">// Predicate.simple(..)</span>
    <span class="k">return</span> <span class="kt">Predicate</span><span class="o">.</span><span class="nf">simpleNilable</span><span class="p">(</span><span class="s">"be nil"</span><span class="p">)</span> <span class="p">{</span> <span class="n">actualExpression</span> <span class="k">in</span>
        <span class="k">let</span> <span class="nv">actualValue</span> <span class="o">=</span> <span class="k">try</span> <span class="n">actualExpression</span><span class="o">.</span><span class="nf">evaluate</span><span class="p">()</span>
        <span class="k">return</span> <span class="kt">PredicateStatus</span><span class="p">(</span><span class="nv">bool</span><span class="p">:</span> <span class="n">actualValue</span> <span class="o">==</span> <span class="kc">nil</span><span class="p">)</span>
    <span class="p">}</span>
<span class="p">}</span>
</code></pre>

<p>In the above example, <code>actualExpression</code> is not <code>nil</code> &ndash; it is a closure
that returns a value. The value it returns, which is accessed via the
<code>evaluate()</code> method, may be <code>nil</code>. If that value is <code>nil</code>, the <code>beNil</code>
matcher function returns <code>true</code>, indicating that the expectation passed.</p>
<h2 id='type-checking-via-swift-generics' class='heading'>Type Checking via Swift Generics</h2>

<p>Using Swift&rsquo;s generics, matchers can constrain the type of the actual value
passed to the <code>expect</code> function by modifying the return type.</p>

<p>For example, the following matcher, <code>haveDescription</code>, only accepts actual
values that implement the <code>Printable</code> protocol. It checks their <code>description</code>
against the one provided to the matcher function, and passes if they are the same:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="kd">public</span> <span class="kd">func</span> <span class="nf">haveDescription</span><span class="p">(</span><span class="nv">description</span><span class="p">:</span> <span class="kt">String</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kt">Predicate</span><span class="o">&lt;</span><span class="kt">Printable</span><span class="p">?</span><span class="o">&gt;</span> <span class="p">{</span>
    <span class="k">return</span> <span class="kt">Predicate</span><span class="o">.</span><span class="nf">simple</span><span class="p">(</span><span class="s">"have description"</span><span class="p">)</span> <span class="p">{</span> <span class="n">actual</span> <span class="k">in</span>
        <span class="k">return</span> <span class="kt">PredicateStatus</span><span class="p">(</span><span class="nv">bool</span><span class="p">:</span> <span class="n">actual</span><span class="o">.</span><span class="nf">evaluate</span><span class="p">()</span><span class="o">.</span><span class="n">description</span> <span class="o">==</span> <span class="n">description</span><span class="p">)</span>
    <span class="p">}</span>
<span class="p">}</span>
</code></pre>
<h2 id='customizing-failure-messages' class='heading'>Customizing Failure Messages</h2>

<p>When using <code>Predicate.simple(..)</code> or <code>Predicate.simpleNilable(..)</code>, Nimble
outputs the following failure message when an expectation fails:</p>
<pre class="highlight swift"><code><span class="c1">// where `message` is the first string argument and</span>
<span class="c1">// `actual` is the actual value received in `expect(..)`</span>
<span class="s">"expected to </span><span class="se">\(</span><span class="n">message</span><span class="se">)</span><span class="s">, got &lt;</span><span class="se">\(</span><span class="n">actual</span><span class="se">)</span><span class="s">&gt;"</span>
</code></pre>

<p>You can customize this message by modifying the way you create a <code><a href="Structs/Predicate.html">Predicate</a></code>.</p>
<h3 id='basic-customization' class='heading'>Basic Customization</h3>

<p>For slightly more complex error messaging, receive the created failure message
with <code>Predicate.define(..)</code>:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="kd">public</span> <span class="kd">func</span> <span class="n">equal</span><span class="o">&lt;</span><span class="kt">T</span><span class="p">:</span> <span class="kt">Equatable</span><span class="o">&gt;</span><span class="p">(</span><span class="n">_</span> <span class="nv">expectedValue</span><span class="p">:</span> <span class="kt">T</span><span class="p">?)</span> <span class="o">-&gt;</span> <span class="kt">Predicate</span><span class="o">&lt;</span><span class="kt">T</span><span class="o">&gt;</span> <span class="p">{</span>
    <span class="k">return</span> <span class="kt">Predicate</span><span class="o">.</span><span class="nf">define</span><span class="p">(</span><span class="s">"equal &lt;</span><span class="se">\(</span><span class="nf">stringify</span><span class="p">(</span><span class="n">expectedValue</span><span class="p">)</span><span class="se">)</span><span class="s">&gt;"</span><span class="p">)</span> <span class="p">{</span> <span class="n">actualExpression</span><span class="p">,</span> <span class="n">msg</span> <span class="k">in</span>
        <span class="k">let</span> <span class="nv">actualValue</span> <span class="o">=</span> <span class="k">try</span> <span class="n">actualExpression</span><span class="o">.</span><span class="nf">evaluate</span><span class="p">()</span>
        <span class="k">let</span> <span class="nv">matches</span> <span class="o">=</span> <span class="n">actualValue</span> <span class="o">==</span> <span class="n">expectedValue</span> <span class="o">&amp;&amp;</span> <span class="n">expectedValue</span> <span class="o">!=</span> <span class="kc">nil</span>
        <span class="k">if</span> <span class="n">expectedValue</span> <span class="o">==</span> <span class="kc">nil</span> <span class="o">||</span> <span class="n">actualValue</span> <span class="o">==</span> <span class="kc">nil</span> <span class="p">{</span>
            <span class="k">if</span> <span class="n">expectedValue</span> <span class="o">==</span> <span class="kc">nil</span> <span class="o">&amp;&amp;</span> <span class="n">actualValue</span> <span class="o">!=</span> <span class="kc">nil</span> <span class="p">{</span>
                <span class="k">return</span> <span class="kt">PredicateResult</span><span class="p">(</span>
                    <span class="nv">status</span><span class="p">:</span> <span class="o">.</span><span class="n">fail</span><span class="p">,</span>
                    <span class="nv">message</span><span class="p">:</span> <span class="n">msg</span><span class="o">.</span><span class="nf">appendedBeNilHint</span><span class="p">()</span>
                <span class="p">)</span>
            <span class="p">}</span>
            <span class="k">return</span> <span class="kt">PredicateResult</span><span class="p">(</span><span class="nv">status</span><span class="p">:</span> <span class="o">.</span><span class="n">fail</span><span class="p">,</span> <span class="nv">message</span><span class="p">:</span> <span class="n">msg</span><span class="p">)</span>
        <span class="p">}</span>
        <span class="k">return</span> <span class="kt">PredicateResult</span><span class="p">(</span><span class="nv">bool</span><span class="p">:</span> <span class="n">matches</span><span class="p">,</span> <span class="nv">message</span><span class="p">:</span> <span class="n">msg</span><span class="p">)</span>
    <span class="p">}</span>
<span class="p">}</span>
</code></pre>

<p>In the example above, <code>msg</code> is defined based on the string given to
<code>Predicate.define</code>. The code looks akin to:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="k">let</span> <span class="nv">msg</span> <span class="o">=</span> <span class="kt">ExpectationMessage</span><span class="o">.</span><span class="nf">expectedActualValueTo</span><span class="p">(</span><span class="s">"equal &lt;</span><span class="se">\(</span><span class="nf">stringify</span><span class="p">(</span><span class="n">expectedValue</span><span class="p">)</span><span class="se">)</span><span class="s">&gt;"</span><span class="p">)</span>
</code></pre>
<h3 id='full-customization' class='heading'>Full Customization</h3>

<p>To fully customize the behavior of the Predicate, use the overload that expects
a <code><a href="Structs/PredicateResult.html">PredicateResult</a></code> to be returned.</p>

<p>Along with <code><a href="Structs/PredicateResult.html">PredicateResult</a></code>, there are other <code><a href="Enums/ExpectationMessage.html">ExpectationMessage</a></code> enum values you can use:</p>
<pre class="highlight swift"><code><span class="kd">public</span> <span class="kd">indirect</span> <span class="kd">enum</span> <span class="kt">ExpectationMessage</span> <span class="p">{</span>
<span class="c1">// Emits standard error message:</span>
<span class="c1">// eg - "expected to &lt;message&gt;, got &lt;actual&gt;"</span>
<span class="k">case</span> <span class="nf">expectedActualValueTo</span><span class="p">(</span><span class="cm">/* message: */</span> <span class="kt">String</span><span class="p">)</span>

<span class="c1">// Allows any free-form message</span>
<span class="c1">// eg - "&lt;message&gt;"</span>
<span class="k">case</span> <span class="nf">fail</span><span class="p">(</span><span class="cm">/* message: */</span> <span class="kt">String</span><span class="p">)</span>

<span class="c1">// Emits standard error message with a custom actual value instead of the default.</span>
<span class="c1">// eg - "expected to &lt;message&gt;, got &lt;actual&gt;"</span>
<span class="k">case</span> <span class="nf">expectedCustomValueTo</span><span class="p">(</span><span class="cm">/* message: */</span> <span class="kt">String</span><span class="p">,</span> <span class="cm">/* actual: */</span> <span class="kt">String</span><span class="p">)</span>

<span class="c1">// Emits standard error message without mentioning the actual value</span>
<span class="c1">// eg - "expected to &lt;message&gt;"</span>
<span class="k">case</span> <span class="nf">expectedTo</span><span class="p">(</span><span class="cm">/* message: */</span> <span class="kt">String</span><span class="p">)</span>

<span class="c1">// ...</span>
<span class="p">}</span>
</code></pre>

<p>For matchers that compose other matchers, there are a handful of helper
functions to annotate messages.</p>

<p><code>appended(message: String)</code> is used to append to the original failure message:</p>
<pre class="highlight swift"><code><span class="c1">// produces "expected to be true, got &lt;actual&gt; (use beFalse() for inverse)"</span>
<span class="c1">// appended message do show up inline in Xcode.</span>
<span class="o">.</span><span class="nf">expectedActualValueTo</span><span class="p">(</span><span class="s">"be true"</span><span class="p">)</span><span class="o">.</span><span class="nf">appended</span><span class="p">(</span><span class="nv">message</span><span class="p">:</span> <span class="s">" (use beFalse() for inverse)"</span><span class="p">)</span>
</code></pre>

<p>For a more comprehensive message that spans multiple lines, use
<code>appended(details: String)</code> instead:</p>
<pre class="highlight swift"><code><span class="c1">// produces "expected to be true, got &lt;actual&gt;\n\nuse beFalse() for inverse\nor use beNil()"</span>
<span class="c1">// details do not show inline in Xcode, but do show up in test logs.</span>
<span class="o">.</span><span class="nf">expectedActualValueTo</span><span class="p">(</span><span class="s">"be true"</span><span class="p">)</span><span class="o">.</span><span class="nf">appended</span><span class="p">(</span><span class="nv">details</span><span class="p">:</span> <span class="s">"use beFalse() for inverse</span><span class="se">\n</span><span class="s">or use beNil()"</span><span class="p">)</span>
</code></pre>
<h2 id='supporting-objective-c' class='heading'>Supporting Objective-C</h2>

<p>To use a custom matcher written in Swift from Objective-C, you&rsquo;ll have
to extend the <code><a href="Classes/NMBPredicate.html">NMBPredicate</a></code> class, adding a new class method for your
custom matcher. The example below defines the class method
<code>+[NMBPredicate beNilMatcher]</code>:</p>
<pre class="highlight swift"><code><span class="c1">// Swift</span>

<span class="kd">extension</span> <span class="kt">NMBPredicate</span> <span class="p">{</span>
    <span class="kd">@objc</span> <span class="kd">public</span> <span class="kd">class</span> <span class="kd">func</span> <span class="nf">beNilMatcher</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="kt">NMBPredicate</span> <span class="p">{</span>
        <span class="k">return</span> <span class="kt">NMBPredicate</span> <span class="p">{</span> <span class="n">actualExpression</span> <span class="k">in</span>
            <span class="k">return</span> <span class="k">try</span> <span class="nf">beNil</span><span class="p">()</span><span class="o">.</span><span class="nf">satisfies</span><span class="p">(</span><span class="n">actualExpression</span><span class="p">)</span><span class="o">.</span><span class="nf">toObjectiveC</span><span class="p">()</span>
        <span class="p">}</span>
    <span class="p">}</span>
<span class="p">}</span>
</code></pre>

<p>The above allows you to use the matcher from Objective-C:</p>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="n">expect</span><span class="p">(</span><span class="n">actual</span><span class="p">).</span><span class="n">to</span><span class="p">([</span><span class="n">NMBPredicate</span> <span class="nf">beNilMatcher</span><span class="p">]());</span>
</code></pre>

<p>To make the syntax easier to use, define a C function that calls the
class method:</p>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="n">FOUNDATION_EXPORT</span> <span class="n">NMBPredicate</span> <span class="o">*</span><span class="nf">beNil</span><span class="p">()</span> <span class="p">{</span>
    <span class="k">return</span> <span class="p">[</span><span class="n">NMBPredicate</span> <span class="nf">beNilMatcher</span><span class="p">];</span>
<span class="p">}</span>
</code></pre>
<h3 id='properly-handling-code-nil-code-in-objective-c-matchers' class='heading'>Properly Handling <code>nil</code> in Objective-C Matchers</h3>

<p>When supporting Objective-C, make sure you handle <code>nil</code> appropriately.
Like <a href="https://github.com/pivotal/cedar/issues/100">Cedar</a>,
<strong>most matchers do not match with nil</strong>. This is to bring prevent test
writers from being surprised by <code>nil</code> values where they did not expect
them.</p>

<p>Nimble provides the <code>beNil</code> matcher function for test writer that want
to make expectations on <code>nil</code> objects:</p>
<pre class="highlight objective_c"><code><span class="c1">// Objective-C</span>

<span class="n">expect</span><span class="p">(</span><span class="nb">nil</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">equal</span><span class="p">(</span><span class="nb">nil</span><span class="p">));</span> <span class="c1">// fails</span>
<span class="n">expect</span><span class="p">(</span><span class="nb">nil</span><span class="p">).</span><span class="n">to</span><span class="p">(</span><span class="n">beNil</span><span class="p">());</span>    <span class="c1">// passes</span>
</code></pre>

<p>If your matcher does not want to match with nil, you use <code>Predicate.define</code> or <code>Predicate.simple</code>. 
Using those factory methods will automatically generate expected value failure messages when they&rsquo;re nil.</p>
<pre class="highlight swift"><code><span class="kd">public</span> <span class="kd">func</span> <span class="n">beginWith</span><span class="o">&lt;</span><span class="kt">S</span><span class="p">:</span> <span class="kt">Sequence</span><span class="o">&gt;</span><span class="p">(</span><span class="n">_</span> <span class="nv">startingElement</span><span class="p">:</span> <span class="kt">S</span><span class="o">.</span><span class="kt">Element</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kt">Predicate</span><span class="o">&lt;</span><span class="kt">S</span><span class="o">&gt;</span> <span class="k">where</span> <span class="kt">S</span><span class="o">.</span><span class="kt">Element</span><span class="p">:</span> <span class="kt">Equatable</span> <span class="p">{</span>
    <span class="k">return</span> <span class="kt">Predicate</span><span class="o">.</span><span class="nf">simple</span><span class="p">(</span><span class="s">"begin with &lt;</span><span class="se">\(</span><span class="n">startingElement</span><span class="se">)</span><span class="s">&gt;"</span><span class="p">)</span> <span class="p">{</span> <span class="n">actualExpression</span> <span class="k">in</span>
        <span class="k">guard</span> <span class="k">let</span> <span class="nv">actualValue</span> <span class="o">=</span> <span class="k">try</span> <span class="n">actualExpression</span><span class="o">.</span><span class="nf">evaluate</span><span class="p">()</span> <span class="k">else</span> <span class="p">{</span> <span class="k">return</span> <span class="o">.</span><span class="n">fail</span> <span class="p">}</span>

        <span class="k">var</span> <span class="nv">actualGenerator</span> <span class="o">=</span> <span class="n">actualValue</span><span class="o">.</span><span class="nf">makeIterator</span><span class="p">()</span>
        <span class="k">return</span> <span class="kt">PredicateStatus</span><span class="p">(</span><span class="nv">bool</span><span class="p">:</span> <span class="n">actualGenerator</span><span class="o">.</span><span class="nf">next</span><span class="p">()</span> <span class="o">==</span> <span class="n">startingElement</span><span class="p">)</span>
    <span class="p">}</span>
<span class="p">}</span>

<span class="kd">extension</span> <span class="kt">NMBPredicate</span> <span class="p">{</span>
    <span class="kd">@objc</span> <span class="kd">public</span> <span class="kd">class</span> <span class="kd">func</span> <span class="nf">beginWithMatcher</span><span class="p">(</span><span class="n">_</span> <span class="nv">expected</span><span class="p">:</span> <span class="kt">Any</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kt">NMBPredicate</span> <span class="p">{</span>
        <span class="k">return</span> <span class="kt">NMBPredicate</span> <span class="p">{</span> <span class="n">actualExpression</span> <span class="k">in</span>
            <span class="k">let</span> <span class="nv">actual</span> <span class="o">=</span> <span class="k">try</span> <span class="n">actualExpression</span><span class="o">.</span><span class="nf">evaluate</span><span class="p">()</span>
            <span class="k">let</span> <span class="nv">expr</span> <span class="o">=</span> <span class="n">actualExpression</span><span class="o">.</span><span class="n">cast</span> <span class="p">{</span> <span class="nv">$0</span> <span class="k">as?</span> <span class="kt">NMBOrderedCollection</span> <span class="p">}</span>
            <span class="k">return</span> <span class="k">try</span> <span class="nf">beginWith</span><span class="p">(</span><span class="n">expected</span><span class="p">)</span><span class="o">.</span><span class="nf">satisfies</span><span class="p">(</span><span class="n">expr</span><span class="p">)</span><span class="o">.</span><span class="nf">toObjectiveC</span><span class="p">()</span>
        <span class="p">}</span>
    <span class="p">}</span>
<span class="p">}</span>
</code></pre>
<h2 id='migrating-from-the-old-matcher-api' class='heading'>Migrating from the Old Matcher API</h2>

<p>Previously (<code>&lt;7.0.0</code>), Nimble supported matchers via the following types:</p>

<ul>
<li><code>Matcher</code></li>
<li><code>NonNilMatcherFunc</code></li>
<li><code>MatcherFunc</code></li>
</ul>

<p>All of those types have been replaced by <code><a href="Structs/Predicate.html">Predicate</a></code>. The old API has been
removed completely in Nimble v10.</p>
<h1 id='installing-nimble' class='heading'>Installing Nimble</h1>

<blockquote>
<p>Nimble can be used on its own, or in conjunction with its sister
  project, <a href="https://github.com/Quick/Quick">Quick</a>. To install both
  Quick and Nimble, follow <a href="https://github.com/Quick/Quick/blob/main/Documentation/en-us/InstallingQuick.md">the installation instructions in the Quick
  Documentation</a>.</p>
</blockquote>

<p>Nimble can currently be installed in one of two ways: using CocoaPods, or with
git submodules.</p>
<h2 id='installing-nimble-as-a-submodule' class='heading'>Installing Nimble as a Submodule</h2>

<p>To use Nimble as a submodule to test your macOS, iOS or tvOS applications, follow
these 4 easy steps:</p>

<ol>
<li>Clone the Nimble repository</li>
<li>Add Nimble.xcodeproj to the Xcode workspace for your project</li>
<li>Link Nimble.framework to your test target</li>
<li>Start writing expectations!</li>
</ol>

<p>For more detailed instructions on each of these steps,
read <a href="https://github.com/Quick/Quick#how-to-install-quick">How to Install Quick</a>.
Ignore the steps involving adding Quick to your project in order to
install just Nimble.</p>
<h2 id='installing-nimble-via-cocoapods' class='heading'>Installing Nimble via CocoaPods</h2>

<p>To use Nimble in CocoaPods to test your macOS, iOS or tvOS applications, add
Nimble to your podfile and add the <code>use_frameworks!</code> line to enable Swift
support for CocoaPods.</p>
<pre class="highlight ruby"><code><span class="n">platform</span> <span class="ss">:ios</span><span class="p">,</span> <span class="s1">'8.0'</span>

<span class="n">source</span> <span class="s1">'https://github.com/CocoaPods/Specs.git'</span>

<span class="c1"># Whatever pods you need for your app go here</span>

<span class="n">target</span> <span class="s1">'YOUR_APP_NAME_HERE_Tests'</span><span class="p">,</span> <span class="ss">:exclusive</span> <span class="o">=&gt;</span> <span class="kp">true</span> <span class="k">do</span>
  <span class="n">use_frameworks!</span>
  <span class="n">pod</span> <span class="s1">'Nimble'</span>
<span class="k">end</span>
</code></pre>

<p>Finally run <code>pod install</code>.</p>
<h2 id='using-nimble-without-xctest' class='heading'>Using Nimble without XCTest</h2>

<p>Nimble is integrated with XCTest to allow it work well when used in Xcode test
bundles, however it can also be used in a standalone app. After installing
Nimble using one of the above methods, there are two additional steps required
to make this work.</p>

<ol>
<li>Create a custom assertion handler and assign an instance of it to the
global <code><a href="Global%20Variables.html#/s:6Nimble0A16AssertionHandlerAA0bC0_pvp">NimbleAssertionHandler</a></code> variable. For example:</li>
</ol>
<pre class="highlight swift"><code><span class="kd">class</span> <span class="kt">MyAssertionHandler</span> <span class="p">:</span> <span class="kt">AssertionHandler</span> <span class="p">{</span>
    <span class="kd">func</span> <span class="nf">assert</span><span class="p">(</span><span class="nv">assertion</span><span class="p">:</span> <span class="kt">Bool</span><span class="p">,</span> <span class="nv">message</span><span class="p">:</span> <span class="kt">FailureMessage</span><span class="p">,</span> <span class="nv">location</span><span class="p">:</span> <span class="kt">SourceLocation</span><span class="p">)</span> <span class="p">{</span>
        <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">assertion</span><span class="p">)</span> <span class="p">{</span>
            <span class="nf">print</span><span class="p">(</span><span class="s">"Expectation failed: </span><span class="se">\(</span><span class="n">message</span><span class="o">.</span><span class="n">stringValue</span><span class="se">)</span><span class="s">"</span><span class="p">)</span>
        <span class="p">}</span>
    <span class="p">}</span>
<span class="p">}</span>
</code></pre>
<pre class="highlight swift"><code><span class="c1">// Somewhere before you use any assertions</span>
<span class="kt">NimbleAssertionHandler</span> <span class="o">=</span> <span class="kt">MyAssertionHandler</span><span class="p">()</span>
</code></pre>

<ol>
<li>Add a post-build action to fix an issue with the Swift XCTest support
library being unnecessarily copied into your app

<ul>
<li>Edit your scheme in Xcode, and navigate to Build -&gt; Post-actions</li>
<li>Click the &ldquo;+&rdquo; icon and select &ldquo;New Run Script Action&rdquo;</li>
<li>Open the &ldquo;Provide build settings from&rdquo; dropdown and select your target</li>
<li>Enter the following script contents:
<code>
rm &quot;${SWIFT_STDLIB_TOOL_DESTINATION_DIR}/libswiftXCTest.dylib&quot;
</code></li>
</ul></li>
</ol>

<p>You can now use Nimble assertions in your code and handle failures as you see
fit.</p>

          </section>
        </section>
        <section id="footer">
          <p>&copy; 2022 <a class="link" href="https://github.com/Quick/Nimble" target="_blank" rel="external noopener">Nimble Contributors</a>. All rights reserved. (Last updated: 2022-04-26)</p>
          <p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external noopener">jazzy ♪♫ v0.14.2</a>, a <a class="link" href="https://realm.io" target="_blank" rel="external noopener">Realm</a> project.</p>
        </section>
      </article>
    </div>
  </body>
</html>
